@k2b/ui 0.49.0 → 0.51.0

package/dist/types/layout/AppWorkspace.d.ts

@@ -306,6 +306,11 @@ export type AppWorkspaceSidebarItemProps = {
     scroll?: NavigationScrollMode;
     onNavigate?: (event: LinkNavigateEvent) => void | Promise<void>;
     onClick?: (event: MouseEvent) => void;
+    /**
+     * Makes a row without `href` a disclosure: it shows or hides the rows after
+     * it, and assistive technology hears whether they are shown.
+     */
+    expanded?: boolean;
     /**
      * Marks the current page (`aria-current="page"`). On a page deeper than the
      * sidebar lists, pass `"ancestor"` for the item that contains it: it keeps

package/dist/types/layout/DetailPanel.d.ts

@@ -74,12 +74,24 @@ export type DetailPanelActionSecondary = {
     onClick: () => void;
     variant?: "danger";
 };
+/**
+ * A checkbox before the row that toggles on its own, such as "done" for a task the row opens. It always shows its
+ * state, unlike a secondary action, which waits for hover.
+ */
+export type DetailPanelActionCheckbox = {
+    checked: boolean;
+    /** Accessible name, after the row, such as "Done: Call Mrs. Weber". */
+    label: string;
+    onChange: (checked: boolean) => void;
+    disabled?: boolean;
+};
 type DetailPanelActionBaseProps = {
     title: JSX.Element;
     description?: JSX.Element;
     leading?: JSX.Element;
     trailing?: JSX.Element;
     secondaryAction?: DetailPanelActionSecondary;
+    checkbox?: DetailPanelActionCheckbox;
     /** Marks the row of the current place, such as the section in view, in the panel's accent. */
     current?: boolean;
     /** Lets the title wrap to two lines instead of ending with an ellipsis. */

package/dist/types/layout/index.d.ts

@@ -12,7 +12,7 @@ export { APP_WORKSPACE_DETAIL_DEFAULT, APP_WORKSPACE_DETAIL_MAX, APP_WORKSPACE_D
 export { type BottomSheetProps, bottomSheetAdaptiveOptions, bottomSheetOptions, default as BottomSheet } from "./BottomSheet";
 export type { DataPanelProps } from "./DataPanel";
 export { DataPanel } from "./DataPanel";
-export type { DetailPanelActionButtonProps, DetailPanelActionLinkProps, DetailPanelActionProps, DetailPanelActionSecondary, DetailPanelBodyProps, DetailPanelGroupProps, DetailPanelHeaderProps, DetailPanelProps, DetailPanelRowProps, DetailPanelSectionProps, DetailPanelSummaryProps, DetailPanelTone, } from "./DetailPanel";
+export type { DetailPanelActionButtonProps, DetailPanelActionCheckbox, DetailPanelActionLinkProps, DetailPanelActionProps, DetailPanelActionSecondary, DetailPanelBodyProps, DetailPanelGroupProps, DetailPanelHeaderProps, DetailPanelProps, DetailPanelRowProps, DetailPanelSectionProps, DetailPanelSummaryProps, DetailPanelTone, } from "./DetailPanel";
 export { default as DetailPanel } from "./DetailPanel";
 export type { DetailAccessEntry, DetailAccessProps, DetailLinkItem, DetailLinksProps, DetailPresencePerson, DetailPresenceProps, DetailPresenceState, DetailPropertiesProps, DetailProperty, DetailTag, DetailTagsProps, } from "./DetailSections";
 export { DetailAccess, DetailLinks, DetailPresence, DetailPresenceSlot, DetailProperties, DetailTags } from "./DetailSections";

package/dist/types/surfaces/BudgetList.d.ts

@@ -0,0 +1,42 @@
+import { type JSX } from "solid-js";
+/** One budget: `used` is booked, `expected` comes on top; over the budget is `used + expected - limit`. */
+export type BudgetItem = {
+    id?: string;
+    label: string;
+    used: number;
+    expected?: number;
+    limit: number;
+};
+export type BudgetListProps = {
+    items: readonly BudgetItem[];
+    /** ISO 4217 currency code, e.g. `"EUR"`. */
+    currency: string;
+    /** Explicit locale override; defaults to the inherited render locale. */
+    locale?: string;
+    /** Fixed fraction digits. Defaults to 0. */
+    decimals?: number;
+    /** The sentence shown when there is no budget. */
+    empty?: string;
+    /** Hides the legend under the rows when the host explains the colours elsewhere. */
+    legend?: boolean;
+    class?: string;
+};
+/** "near" from 80 % of the budget, "over" beyond it. */
+export type BudgetLevel = "ok" | "near" | "over";
+/** The figures of one budget row; the share counts booked and expected together. */
+export declare const budgetState: (item: Pick<BudgetItem, "used" | "expected" | "limit">) => {
+    used: number;
+    expected: number;
+    limit: number;
+    total: number;
+    over: number;
+    free: number;
+    ratio: number;
+    level: BudgetLevel;
+};
+/**
+ * Budgets as rows: label and "spent of budget", a bar with booked (solid), expected (hatched) and over the budget
+ * (red, with a mark at the limit), and a hint that turns amber from 80 % and red beyond the budget.
+ */
+export declare function BudgetList(props: BudgetListProps): JSX.Element;
+export default BudgetList;

package/dist/types/surfaces/DescriptionList.d.ts

@@ -10,6 +10,11 @@ export type DescriptionListProps = {
     layout?: "grid" | "rows" | "compact";
     size?: "sm" | "md";
     actionVisibility?: "always" | "progressive";
+    /**
+     * Joins each term to its right-aligned value with a dotted leader, for `rows` or `compact` lists that must span a
+     * very wide container. A fallback, never the default: first keep rows within the row measure.
+     */
+    leader?: "dotted";
     class?: string;
 };
 /** Semantic key-value content with predictable responsive density. */

package/dist/types/surfaces/ProgressBar.d.ts

@@ -1,13 +1,49 @@
-import type { JSX } from "solid-js";
+import { type JSX } from "solid-js";
 import type { IntentTone } from "../semantics";
 export type ProgressBarTone = Extract<IntentTone, "info" | "success" | "warning" | "danger">;
-export type ProgressBarProps = {
+/** One part of a segmented bar, in the unit of `limit`. `"hatched"` marks an expected, not yet booked part. */
+export type ProgressBarSegment = {
     value: number;
+    pattern?: "solid" | "hatched";
+};
+export type ProgressBarProps = {
+    /** Percent from 0 to 100. With `segments`, the share of `limit` the segments fill. */
+    value?: number;
     size?: "xs" | "sm" | "md";
     tone?: ProgressBarTone;
     showValue?: boolean;
     label: string;
+    /** Parts drawn in order, such as booked and expected spending. Negative and non-finite values count as 0. */
+    segments?: readonly ProgressBarSegment[];
+    /** The budget the segments fill. What goes beyond it is drawn red, with a mark at the limit. */
+    limit?: number;
+    /** Spoken value, such as "1,240 € of 1,500 €"; defaults to the percent. */
+    valueText?: string;
     class?: string;
 };
+export type ProgressBarPart = {
+    pattern: "solid" | "hatched" | "over";
+    width: number;
+};
+/**
+ * Sum minus limit, without float residue: `0.1 + 0.2` against `0.3` is not over. Amounts within a billionth of the
+ * larger of both count as equal.
+ */
+export declare const budgetOverrun: (total: number, limit: number) => number;
+/** Sum over limit; an empty budget with spending is infinitely full. */
+export declare const budgetRatio: (total: number, limit: number) => number;
+/**
+ * The drawn parts of a segmented bar, each as a percent of the track. The track spans the larger of the limit and the
+ * sum, so an overrun stays visible: segments fill up to the limit in order, the rest is one "over" part, and `mark`
+ * places the limit line (only when the sum goes beyond it). Without `limit` the segments fill the track; a limit of 0,
+ * below 0 or not finite is an empty budget, so any spending is over it.
+ */
+export declare const progressBarParts: (segments: readonly ProgressBarSegment[], limit?: number) => {
+    parts: ProgressBarPart[];
+    total: number;
+    over: number;
+    mark: number | null;
+    ratio: number;
+};
 export declare function ProgressBar(props: ProgressBarProps): JSX.Element;
 export default ProgressBar;

package/dist/types/surfaces/StatCell.d.ts

@@ -1,4 +1,5 @@
 import { type JSX } from "solid-js";
+import type { ChartNumberFormat } from "../charts/description";
 import type { ChartTooltipFormatter } from "../content/chart-inspection-core";
 import type { AccentColor } from "../semantics";
 import { type StatGridSize } from "./StatGrid";
@@ -8,12 +9,39 @@ export type StatCellAccent = {
     icon: string;
     text?: string;
 };
+/**
+ * The change against a comparison period. `unit: "ratio"` (default) reads `0.082` as `+8.2 %`; `"points"` is the
+ * difference of two shares in ratio units, so `0.031` reads `+3.1 pts`. Only with `better` does the badge carry a tone
+ * and say "better" or "worse"; without it the change stays unrated.
+ */
+export type StatCellDelta = {
+    value: number;
+    unit?: "ratio" | "points" | "absolute";
+    /** Existing measures can express a change in their own unit instead of a ratio. */
+    format?: ChartNumberFormat;
+    better?: "up" | "down";
+};
+/** The value the change compares against, shown under the figure, such as "Last month 44,560". */
+export type StatCellCompare = {
+    label: string;
+    value: string | number;
+};
+export type StatCellSize = StatGridSize;
 export type StatCellProps = {
     label: string;
-    value: string | number | JSX.Element;
+    /** The figure. `null` shows the empty dash; `sub` then says why. */
+    value: string | number | JSX.Element | null;
     sub?: string;
     valueClass?: string;
+    /** An icon in a chip before the label, in `tone`. `"in"` and `"out"` are the money colours of `FlowAmount`. */
+    icon?: string;
+    /** The chip colour of `icon`. Defaults to zinc. */
+    tone?: StatCellTone | "in" | "out";
     accent?: StatCellAccent;
+    delta?: StatCellDelta;
+    /** Keep the figure and change on separate rows, including while loading. Defaults to beside the figure. */
+    deltaPlacement?: "below";
+    compare?: StatCellCompare;
     href?: string;
     title?: string;
     trend?: readonly number[];
@@ -22,12 +50,22 @@ export type StatCellProps = {
      * `selection.datum.index` is the source index into `trend`.
      */
     trendTooltip?: ChartTooltipFormatter;
-    size?: StatGridSize;
+    size?: StatCellSize;
     /**
      * Wraps the label, value and support line instead of truncating them. Use it for a cell whose height nothing
      * reserves, such as one figure on its own; cells compared in a row keep one line each.
      */
     wrap?: boolean;
+    /** `"loading"` keeps the tile's size with placeholders; `"error"` says the figure did not load. */
+    status?: "loading" | "error";
+    /** Offers "Try again" after an error and "Reload" beside `stale`. */
+    onRetry?: () => void;
+    /** The figure is not current: a short note such as "As of 09:12 · not current" replaces the support line. */
+    stale?: string;
 };
+/**
+ * One key figure as a framed tile: icon and label, the figure with its change, and a support line with the comparison
+ * and the trend. Each state (loading, error, stale, empty) keeps the tile's place and size.
+ */
 export declare function StatCell(props: StatCellProps): JSX.Element;
 export default StatCell;

package/dist/types/surfaces/StatGrid.d.ts

@@ -1,5 +1,5 @@
 import { type JSX } from "solid-js";
-export type StatGridSize = "md" | "sm";
+export type StatGridSize = "lg" | "md" | "sm";
 export type StatGridSurface = "white" | "muted";
 export type StatGridColumns = 1 | 2 | 3 | 4 | 5 | 6;
 export type StatGridAction = {
@@ -10,6 +10,7 @@ export type StatGridProps = {
     children: JSX.Element;
     title?: string;
     action?: StatGridAction;
+    /** Tiles per row on a wide container. Defaults to 4; at 600 px or less two share a row, and five or six take three up to 900 px. */
     columns?: StatGridColumns;
     size?: StatGridSize;
     surface?: StatGridSurface;
@@ -17,5 +18,6 @@ export type StatGridProps = {
 };
 export declare const useStatGridSize: () => StatGridSize;
 export declare const useStatGridSurface: () => StatGridSurface;
+/** A row of key figures, each a framed tile of its own; the optional title and action sit above the row. */
 export declare function StatGrid(props: StatGridProps): JSX.Element;
 export default StatGrid;

package/dist/types/surfaces/budget-messages.d.ts

@@ -0,0 +1,30 @@
+declare const budgetMessages: import("@k2b/stdlib").Catalog<{
+    of: ({ limit }: {
+        limit: string;
+    }) => string;
+    free: ({ amount }: {
+        amount: string;
+    }) => string;
+    near: ({ amount }: {
+        amount: string;
+    }) => string;
+    over: ({ amount }: {
+        amount: string;
+    }) => string;
+    used: string;
+    expected: string;
+    overLegend: string;
+    budget: string;
+    left: string;
+    overBy: string;
+    valueText: ({ used, expected, limit }: {
+        used: string;
+        expected?: string;
+        limit: string;
+    }) => string;
+}>;
+export type BudgetMessages = ReturnType<(typeof budgetMessages)["resolve"]>["t"];
+/** Resolved from an explicit locale override, else the inherited render locale. */
+export declare const useBudgetMessages: (override?: () => string | undefined) => (() => BudgetMessages);
+export declare const checkBudgetMessages: () => import("@k2b/stdlib").CatalogIssue[];
+export {};

package/dist/types/surfaces/delta-badge.d.ts

@@ -0,0 +1,10 @@
+import type { JSX } from "solid-js";
+import type { StatCellCompare, StatCellDelta } from "./StatCell";
+import { type StatCellMessages } from "./stat-cell-messages";
+/** Signed with a true minus sign (U+2212), as figures are typeset. */
+export declare const deltaText: (delta: StatCellDelta, locale: string, t: StatCellMessages) => string;
+/** A change badge: arrow, signed text, and a spoken label that names the comparison and, with `better`, the rating. */
+export declare function DeltaBadge(props: {
+    delta: StatCellDelta;
+    compare?: StatCellCompare;
+}): JSX.Element;

package/dist/types/surfaces/index.d.ts

@@ -2,6 +2,7 @@ export type { AvatarProps, AvatarRing, AvatarShape, AvatarSize, AvatarTone } fro
 export { Avatar } from "./Avatar";
 export type { AvatarFacesPerson, AvatarFacesProps, AvatarStackPerson, AvatarStackProps } from "./AvatarStack";
 export { AvatarFaces, AvatarStack } from "./AvatarStack";
+export { type BudgetItem, type BudgetLevel, BudgetList, type BudgetListProps, budgetState } from "./BudgetList";
 export type { ChangeListItem, ChangeListProps, ChangeTone } from "./ChangeList";
 export { ChangeList } from "./ChangeList";
 export type { DescriptionListItem, DescriptionListProps } from "./DescriptionList";
@@ -18,15 +19,15 @@ export type { PaperProps, PaperTag } from "./Paper";
 export { Paper } from "./Paper";
 export type { PlaceholderAlign, PlaceholderProps, PlaceholderState, PlaceholderSurface, PlaceholderVariant, } from "./Placeholder";
 export { default as Placeholder } from "./Placeholder";
-export type { ProgressBarProps, ProgressBarTone } from "./ProgressBar";
-export { ProgressBar } from "./ProgressBar";
+export type { ProgressBarPart, ProgressBarProps, ProgressBarSegment, ProgressBarTone } from "./ProgressBar";
+export { ProgressBar, progressBarParts } from "./ProgressBar";
 export type { ProgressRingProps, ProgressRingTone } from "./ProgressRing";
 export { ProgressRing } from "./ProgressRing";
 export { PERSON_COLORS, personColor } from "./person-color";
 export type { ResourceCardColor, ResourceCardProps, ResourceCardState } from "./ResourceCard";
 export { ResourceCard } from "./ResourceCard";
 export { Skeleton, type SkeletonProps } from "./Skeleton";
-export type { StatCellAccent, StatCellProps, StatCellTone } from "./StatCell";
+export type { StatCellAccent, StatCellCompare, StatCellDelta, StatCellProps, StatCellSize, StatCellTone } from "./StatCell";
 export { StatCell } from "./StatCell";
 export type { StatGridAction, StatGridColumns, StatGridProps, StatGridSize, StatGridSurface, } from "./StatGrid";
 export { StatGrid } from "./StatGrid";

package/dist/types/surfaces/person-color.d.ts

@@ -1,9 +1,9 @@
 /**
  * The colors that stand for a person: the tint behind avatar initials, a collaborator's cursor, and the marks and
- * comments a person leaves. The palette leaves out cyan, which means AI, and yellow, which reads as a text highlight.
+ * comments a person leaves. The palette leaves out plum, which means AI, and yellow, which reads as a text highlight.
  * Several people can share a color, so a person's name always appears next to it.
  */
-export declare const PERSON_COLORS: readonly ["#3b82f6", "#6366f1", "#8b5cf6", "#c026d3", "#ec4899", "#e11d48", "#f97316", "#16a34a"];
+export declare const PERSON_COLORS: readonly ["#3b82f6", "#6366f1", "#8b5cf6", "#0891b2", "#0d9488", "#e11d48", "#f97316", "#16a34a"];
 /** The palette index for a name, the order of the `.k2b-avatar[data-tint]` rules. Surrounding spaces do not count. */
 export declare const personTint: (name: string) => number;
 /** A person's color from their display name, the same wherever Cloud shows that person. */

package/dist/types/surfaces/stat-cell-messages.d.ts

@@ -0,0 +1,19 @@
+declare const statCellMessages: import("@k2b/stdlib").Catalog<{
+    points: string;
+    better: string;
+    worse: string;
+    comparedWith: ({ label }: {
+        label: string;
+    }) => string;
+    notLoaded: string;
+    retry: string;
+    reload: string;
+    loading: string;
+}>;
+export type StatCellMessages = ReturnType<(typeof statCellMessages)["resolve"]>["t"];
+/** Resolved from the inherited render locale. */
+export declare const useStatCellMessages: () => (() => StatCellMessages);
+/** For a caller that already holds the locale, such as table text for search and copy. */
+export declare const resolveStatCellMessages: (locale: string) => StatCellMessages;
+export declare const checkStatCellMessages: () => import("@k2b/stdlib").CatalogIssue[];
+export {};

package/dist/types/widgets/Dashboard.d.ts

@@ -0,0 +1,42 @@
+import { type JSX } from "solid-js";
+/**
+ * A panel's share of the six dashboard columns: a third is two, a half three, two thirds four, full all six. At a
+ * dashboard width of 1000 px or less a third takes half the row and two thirds the whole row; at 600 px or less every
+ * panel takes the whole row.
+ */
+export type DashboardWidth = "third" | "half" | "twoThirds" | "full";
+export type DashboardGridProps = {
+    children: JSX.Element;
+    class?: string;
+};
+/** The dashboard's measuring container. Panel widths and the key-figure row follow its width, not the window's. */
+export declare function DashboardGrid(props: DashboardGridProps): JSX.Element;
+export type DashboardSectionProps = {
+    /** Visible heading; without it the section has no heading and is named by `ariaLabel`. */
+    title?: string;
+    /** Tabler icon class shown as a plain glyph before the title, never in a tile. */
+    icon?: string;
+    /** Colour of the icon glyph; it is mixed with the text colour so it stays readable in light and dark. */
+    iconColor?: string;
+    /** Source or cadence, quiet and next to the title. */
+    description?: string;
+    headingLevel?: 2 | 3 | 4;
+    ariaLabel?: string;
+    class?: string;
+    /** Panels and at most one key-figure row (`StatGrid`), in reading order; the row always spans all six columns. */
+    children?: JSX.Element;
+};
+/** A titled group of panels on the six-column grid. */
+export declare function DashboardSection(props: DashboardSectionProps): JSX.Element;
+type DashboardPanelTag = "article" | "section" | "div" | "li";
+type DashboardPanelOwnProps<T extends DashboardPanelTag> = {
+    as?: T;
+    /** Defaults to a third. Ignored inside a key-figure row, where every tile takes one of its columns. */
+    width?: DashboardWidth;
+    class?: string;
+    children?: JSX.Element;
+};
+export type DashboardPanelProps<T extends DashboardPanelTag = "article"> = DashboardPanelOwnProps<T> & Omit<JSX.IntrinsicElements[T], keyof DashboardPanelOwnProps<T>>;
+/** One framed cell of the grid. Panels in a row share the height of the tallest. */
+export declare function DashboardPanel<T extends DashboardPanelTag = "article">(props: DashboardPanelProps<T>): JSX.Element;
+export {};

package/dist/types/widgets/DashboardFrame.d.ts

@@ -0,0 +1,58 @@
+import { type JSX } from "solid-js";
+import type { DashboardWidth } from "./Dashboard";
+/**
+ * What the host's read shows: its content (`ready`), the first read in flight (`loading`), nothing to show (`empty`),
+ * a failed first read (`error`), or content whose refresh failed (`stale`).
+ */
+export type DashboardFrameState = "ready" | "loading" | "empty" | "error" | "stale";
+export type DashboardFrameProps = {
+    /**
+     * Heading of the frame. Without it the frame is only the surface, for content that brings its own head and states,
+     * such as `ChartExplorer` with `inset="1rem"`.
+     */
+    title?: string;
+    /** One line under the title; loading and stale notes take its place, so nothing moves. */
+    subtitle?: JSX.Element;
+    /** Level of the title heading; defaults to 3. */
+    headingLevel?: 2 | 3 | 4 | 5 | 6;
+    /** Controls at the right of the head, such as a search field or a grouping chip. */
+    tools?: JSX.Element;
+    /** Defaults to `ready`. */
+    state?: DashboardFrameState;
+    /** When the shown content was read, formatted by the host ("09:12"); a stale note names it. */
+    asOf?: string;
+    /** Try again after a failure; without it a failure has no button. */
+    onRetry?: () => void;
+    /** The empty sentence, such as "No campaign in this period." */
+    empty?: JSX.Element;
+    /** Tabler icon of the empty state; defaults to `ti ti-chart-bar-off`. */
+    emptyIcon?: string;
+    /** An action under the empty sentence, such as "Clear search". */
+    emptyAction?: JSX.Element;
+    /**
+     * The content has nothing to show right now although the read succeeded, such as a search without matches: the body
+     * shows the empty sentence and action while the head keeps its state, so a stale note stays.
+     */
+    emptyContent?: boolean;
+    /** Height of the body, a CSS length. Every state keeps it. */
+    height?: string;
+    /**
+     * A hidden copy of the full content that holds the body's height in every state, such as every row of a table. The
+     * body then reaches the frame's left, right and bottom edges, like a table that brings its own rows.
+     */
+    reserve?: JSX.Element;
+    /** States as one quiet line instead of a centred message, for short content such as an amount or one bar. */
+    compact?: boolean;
+    /**
+     * Share of a `DashboardSection`'s six columns, like `DashboardPanel`: the frame is the grid cell itself, so it never
+     * sits in a second frame. Defaults to a third there; ignored elsewhere.
+     */
+    width?: DashboardWidth;
+    class?: string;
+    children?: JSX.Element;
+};
+/**
+ * One framed dashboard panel: title, subtitle, tools and the content the host passes, with loading, empty, failure and
+ * stale in the same place and at the same height.
+ */
+export declare function DashboardFrame(props: DashboardFrameProps): JSX.Element;

package/dist/types/widgets/index.d.ts

@@ -1,3 +1,5 @@
+export * from "./Dashboard";
+export * from "./DashboardFrame";
 export * from "./Widget";
 export * from "./WidgetHero";
 export * from "./WidgetList";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/ui",
-  "version": "0.49.0",
+  "version": "0.51.0",
   "description": "Production-ready components for SolidJS applications.",
   "repository": {
     "type": "git",
@@ -54,6 +54,12 @@
       "types": "./dist/types/text-editor/markdown-table.d.ts",
       "import": "./dist/ssr/text-editor/markdown-table.js",
       "default": "./dist/ssr/text-editor/markdown-table.js"
+    },
+    "./charts/core": {
+      "types": "./dist/types/charts/core/index.d.ts",
+      "browser": "./dist/browser/charts/core/index.js",
+      "import": "./dist/ssr/charts/core/index.js",
+      "default": "./dist/ssr/charts/core/index.js"
     }
   },
   "files": [
@@ -88,6 +94,7 @@
     "maplibre-gl": "6.14.0",
     "marked": "18.0.14",
     "pbf": "5.1.2",
+    "pdfjs-dist": "6.3.289",
     "qr-scanner": "1.4.2"
   },
   "peerDependencies": {