@k2b/ui 0.50.0 → 0.52.0

package/dist/types/inputs/period.d.ts

@@ -0,0 +1,134 @@
+/**
+ * A period as an app stores it: a preset key that stays relative ("this month" is next month's month too), or two
+ * explicit days. Days are date keys such as `2026-11-01`; `end` is inclusive.
+ */
+export type PeriodValue = {
+    preset: string;
+} | {
+    start: string;
+    end: string;
+};
+/** Inclusive days of a period. `null` is an open edge, for example "All time" without a known first day. */
+export type PeriodRange = {
+    start: string | null;
+    end: string | null;
+};
+/** What a preset resolves against: today in the period's time zone and the first day of the week. */
+export type PeriodContext = {
+    today: string;
+    weekStartsOn: 0 | 1;
+};
+export type PeriodPreset = {
+    key: string;
+    /** Shown in the list and the trigger. Built-in presets bring a translated label; app presets name their own. */
+    label?: string;
+    resolve: (context: PeriodContext) => PeriodRange;
+};
+/** The clock a period is resolved with. Server and browser pass the same values so the first render agrees. */
+export type PeriodClock = {
+    /** The instant "today" is read from; defaults to now. */
+    now?: Date;
+    /** IANA time zone the days belong to, for example a base's zone; defaults to the runtime zone. */
+    timeZone?: string;
+    /** First day of the week, as in the calendar's date config; Monday by default. */
+    weekStartsOn?: 0 | 1;
+    /** Alias of `weekStartsOn`, accepted from a shared date config. */
+    firstDayOfWeek?: 0 | 1;
+};
+/** Adds whole days to a date key; calendar days, so a DST change never moves it. */
+export declare const addPeriodDays: (key: string, count: number) => string;
+/** Number of days in an inclusive range of date keys. */
+export declare const periodDayCount: (range: {
+    start: string;
+    end: string;
+}) => number;
+/**
+ * Built-in presets. Each covers its whole calendar period ("This month" is the 1st to the last day, not up to
+ * today) in the period's time zone; weeks start on the context's first day of the week.
+ */
+export declare const periodPresets: {
+    today: {
+        key: string;
+        resolve: ({ today }: PeriodContext) => {
+            start: string;
+            end: string;
+        };
+    };
+    yesterday: {
+        key: string;
+        resolve: ({ today }: PeriodContext) => {
+            start: string;
+            end: string;
+        };
+    };
+    thisWeek: {
+        key: string;
+        resolve: (context: PeriodContext) => PeriodRange;
+    };
+    lastWeek: {
+        key: string;
+        resolve: (context: PeriodContext) => PeriodRange;
+    };
+    thisMonth: {
+        key: string;
+        resolve: ({ today }: PeriodContext) => PeriodRange;
+    };
+    lastMonth: {
+        key: string;
+        resolve: ({ today }: PeriodContext) => PeriodRange;
+    };
+    thisQuarter: {
+        key: string;
+        resolve: ({ today }: PeriodContext) => PeriodRange;
+    };
+    lastQuarter: {
+        key: string;
+        resolve: ({ today }: PeriodContext) => PeriodRange;
+    };
+    thisYear: {
+        key: string;
+        resolve: ({ today }: PeriodContext) => PeriodRange;
+    };
+    lastYear: {
+        key: string;
+        resolve: ({ today }: PeriodContext) => PeriodRange;
+    };
+    /** Everything up to today; `since` is the first day with data when the app knows it, else the start stays open. */
+    all: (options?: {
+        since?: string | null;
+    }) => PeriodPreset;
+};
+/** A real calendar day key, not only the shape (`2026-02-30` is refused). */
+export declare const isPeriodDay: (value: unknown) => value is string;
+/** Accepts a stored or URL value only when it is a known preset key or two real days in order. */
+export declare const parsePeriodValue: (value: unknown, presets: readonly PeriodPreset[]) => PeriodValue | undefined;
+/** The context presets resolve against: today in the clock's time zone. */
+export declare const periodContext: (clock?: PeriodClock) => PeriodContext;
+/**
+ * Resolves a value to inclusive days. Returns `undefined` for a preset key the list does not contain, so a stored
+ * period that no longer exists is never silently replaced.
+ */
+export declare const resolvePeriod: (value: PeriodValue, presets: readonly PeriodPreset[], clock?: PeriodClock) => PeriodRange | undefined;
+/**
+ * The instants a query uses for a resolved period: `from` is the start of the first day and `to` the start of the
+ * day after the last one (exclusive), both in the time zone. Days are never assumed to last 24 hours.
+ */
+export declare const periodInstants: (range: PeriodRange, timeZone: string) => {
+    from: string | null;
+    to: string | null;
+};
+/**
+ * Short days of a preset, for the list and the trigger: "Sat, Nov 7", "Nov 1 – 30", "2025", "since 3/14/2019".
+ * The year is added only when the period is not in today's year.
+ */
+export declare const formatPeriodDays: (range: PeriodRange, today: string, locale: string, since: (date: string) => string) => string;
+/** Explicit days as numbers with the year: "01.–07.11.2026" in German, "11/1/2026 – 11/7/2026" in English. */
+export declare const formatPeriodRange: (range: {
+    start: string;
+    end: string;
+}, locale: string) => string;
+/** The widest explicit range within today's year, all of it (two-digit days, a three-digit count), so a trigger can reserve its width. */
+export declare const widePeriodRangeSample: (today: string) => {
+    start: string;
+    end: string;
+};

package/dist/types/internal/field.d.ts

@@ -13,6 +13,8 @@ type FieldLayoutProps = {
     fill?: boolean;
     /** Composite controls use aria-labelledby instead of an HTML label target. */
     labelFor?: string | false;
+    /** Optional controls beside the label, outside its clickable target. */
+    labelEnd?: JSX.Element;
 } & Pick<FieldProps, "class" | "description" | "error" | "label" | "required" | "disabled">;
 export declare function Field(props: FieldLayoutProps): JSX.Element;
 type FieldAriaOwner = Pick<FieldProps, "aria-describedby" | "aria-label" | "description" | "error" | "label" | "required">;

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/PanelDialog.d.ts

@@ -6,6 +6,11 @@ export type PanelDialogProps = {
     surface?: PanelDialogSurface;
     /** A 2 px edge in the tone's colour inside the dialog frame; the header shows the tone's icon instead of its own. */
     tone?: DialogTone;
+    /**
+     * The body shows a picture or a video edge to edge, and the header floats over it as glass chips: the title and
+     * subtitle in one chip, the actions in a group, and the close button. For documents, text, and tables leave it off.
+     */
+    media?: boolean;
 };
 export type PanelDialogHeaderProps = {
     title: JSX.Element;

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/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/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";
@@ -15,7 +16,9 @@ export type StatCellAccent = {
  */
 export type StatCellDelta = {
     value: number;
-    unit?: "ratio" | "points";
+    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". */
@@ -36,6 +39,8 @@ export type StatCellProps = {
     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;

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

@@ -9,6 +9,7 @@ declare const statCellMessages: import("@k2b/stdlib").Catalog<{
     retry: string;
     reload: string;
     loading: string;
+    noValue: string;
 }>;
 export type StatCellMessages = ReturnType<(typeof statCellMessages)["resolve"]>["t"];
 /** Resolved from the inherited render locale. */

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

@@ -0,0 +1,61 @@
+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. With `reserve`, the content fills it and scrolls inside, so
+     * a table keeps its header in view; without it, the hidden copy sets the height.
+     */
+    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,4 +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.50.0",
+  "version": "0.52.0",
   "description": "Production-ready components for SolidJS applications.",
   "repository": {
     "type": "git",
@@ -94,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": {
@@ -103,7 +104,7 @@
   "devDependencies": {
     "@babel/core": "8.0.6",
     "@babel/preset-typescript": "8.0.1",
-    "@k2b/ssr": "0.21.0",
+    "@k2b/ssr": "0.21.1",
     "@types/babel__core": "7.20.5",
     "@types/bun": "1.4.2",
     "axe-core": "4.11.0",