@k2b/ui 0.22.0 → 0.23.0

package/dist/types/content/calendar-shared.d.ts

@@ -0,0 +1,69 @@
+import { type DateContext } from "@k2b/stdlib";
+import type { JSX } from "solid-js";
+import type { CalendarEvent, CalendarProps } from "./Calendar";
+/** One piece of an event in one day, with the times of the whole event. */
+export type NormalizedEvent = CalendarEvent & {
+    startDate: Date;
+    endDate: Date;
+    dayKey: string;
+    sourceStartDate: Date;
+    sourceEndDate: Date;
+};
+/** A keyboard stop of the week grid. */
+export type CalendarStop = {
+    id: string;
+    column: number;
+    minute: number;
+};
+/** What the built-in views read from the props: they only ever link to built-in views. */
+export type CalendarOwner = Omit<CalendarProps, "view" | "customViews" | "children">;
+export declare const ownerDateConfig: (owner: CalendarOwner) => DateContext;
+export declare const parseDate: (value: Date | string, context?: DateContext) => Date;
+export declare const validDate: (value: Date) => boolean;
+export declare const formatTime: (date: Date, context?: DateContext) => string;
+export declare const eventHref: (props: CalendarOwner, event: CalendarEvent) => string | undefined;
+/** Places a calendar popover below its anchor when there is room and above it otherwise, inside the viewport. */
+export declare const placeCalendarPopover: (anchor: Element | DOMRect, popover: HTMLElement) => void;
+/** Follows a calendar link the way the calendar's own links do: through the host's navigation when it has one. */
+export declare const followCalendarHref: (owner: CalendarOwner, href: string) => void;
+export declare const EventChip: (props: {
+    event: NormalizedEvent;
+    owner: CalendarOwner;
+    href?: string;
+    compact?: boolean;
+    fill?: boolean;
+    moving?: boolean;
+    /** Replaces the title and time at the start of the accessible name, for example with the dates a long event spans. */
+    label?: string;
+    /** A bar of a long event that goes on before or after the week row it sits in. */
+    continuesBefore?: boolean;
+    continuesAfter?: boolean;
+    /** Month view: an all-day or multi-day entry drawn as a bar. */
+    bar?: boolean;
+    /** Short dates at the torn ends of a bar, where it continues in another week row. */
+    hintStart?: string;
+    hintEnd?: string;
+    /** Month view: the start time before the title. */
+    leadingTime?: string;
+    /** Day and week views: what is left of a running event, such as "27 min left". */
+    remaining?: string;
+    /** Day and week views: the calendar draws the event's checkbox beside the chip. */
+    checkbox?: boolean;
+    /** Day and week views with `dayHours`: the chip is a band, a deadline, or an all-day entry of a timeline. */
+    timeline?: boolean;
+    /** Text after the content, such as the time of a deadline. */
+    trailing?: JSX.Element;
+    /** Day and week views: the time as they write it, such as "10:30–11:15", shown whatever the length. */
+    timeLabel?: string;
+    /** Day view: a band tall enough shows its place below the time. */
+    showLocation?: boolean;
+    /** Week view: the grid's one tab stop decides which chip takes Tab. */
+    tabIndex?: number;
+    /** A keyboard stop of the week grid: its id, its day column, and its minute for moving between columns. */
+    stop?: CalendarStop;
+    /** Day and week views: Space on the chip checks the box the calendar draws beside it, as on the box itself. */
+    onCheck?: () => void;
+    onMovePointerDown?: (event: PointerEvent, onActivate: () => void) => void;
+}) => JSX.Element;
+/** The width of a text in a font, from a canvas, so a bar can tell whether its title leaves room for a date hint. */
+export declare const textWidth: (text: string, font: string) => number;

package/dist/types/content/calendar-time-view.d.ts

@@ -0,0 +1,252 @@
+import { type DateContext } from "@k2b/stdlib";
+import type { CalendarController, CalendarEvent, CalendarEventTimeChange, CalendarExternalDrag, CalendarLabels } from "./Calendar";
+import { type CalendarDayHours, type DayGap, type DayGeometry, type DayLane, type DayModel, type DaySpan } from "./calendar-days";
+import { type CalendarOwner, type CalendarStop, type NormalizedEvent } from "./calendar-shared";
+/**
+ * Shared state and parts of the day and week views with `dayHours`: the time model of the loaded days, the selection,
+ * the quick create, pointer gestures, and the pieces both views draw into a day's timeline.
+ */
+export type TodayDirection = "left" | "right" | "up" | "down" | "";
+/** What the header and the calendar's controller ask of the active day or week view. */
+export type TimeViewHandle = {
+    /** The first and last day the reader sees. */
+    visibleKeys: () => {
+        first: string;
+        last: string;
+    };
+    /** Moves by a day (day view) or a week (week view) when that is loaded; `false` leaves it to the header's link. */
+    step: (direction: -1 | 1) => boolean;
+    /** Shows a day when it is loaded; `false` leaves it to navigation. */
+    goTo: (key: string) => boolean;
+    /** Shows today and now when they are loaded. */
+    today: () => boolean;
+    todayDirection: () => TodayDirection;
+    controller: CalendarController;
+};
+export type TimeViewProps = {
+    owner: CalendarOwner;
+    view: "day" | "week";
+    date: Date;
+    now: Date;
+    events: readonly CalendarEvent[];
+    labels: Required<CalendarLabels>;
+    hours: CalendarDayHours;
+    register: (handle: TimeViewHandle | null) => void;
+};
+export type TimeSelection = {
+    key: string;
+    start?: number;
+    end?: number;
+};
+type Ghost = {
+    key: string;
+    start: number;
+    end: number;
+    title: string;
+    time: string;
+    colorHex?: string;
+    color?: string;
+    warn?: boolean;
+    fit?: {
+        fits: boolean;
+        text: string;
+    };
+};
+type QuickCreate = {
+    range: CalendarEventTimeChange;
+    anchor: Element | DOMRect;
+    create?: string;
+    key: string;
+    start?: number;
+    end?: number;
+};
+export type BodyHit = {
+    key: string;
+    element: HTMLElement;
+    geometry: DayGeometry;
+    minute: number;
+};
+export declare const eventAccent: (event: Pick<CalendarEvent, "color" | "colorHex">) => string;
+export declare const reducedMotion: () => boolean;
+/** Swallows the click a browser sends right after a gesture ends, never the next one. */
+export declare const swallowNextClick: () => void;
+export declare const createTimeView: (props: TimeViewProps) => {
+    props: TimeViewProps;
+    messages: () => import("./calendar-messages").CalendarMessages;
+    dateConfig: import("solid-js").Accessor<DateContext>;
+    hours: () => CalendarDayHours;
+    wake: import("solid-js").Accessor<number>;
+    range: import("solid-js").Accessor<{
+        first: string;
+        last: string;
+    }>;
+    anchorKey: import("solid-js").Accessor<string>;
+    days: import("solid-js").Accessor<Map<string, DayModel<CalendarEvent>>>;
+    dayOf: (key: string) => DayModel<CalendarEvent>;
+    keyOf: (date: Date) => string;
+    parseKey: (key: string) => Date;
+    nowKey: import("solid-js").Accessor<string>;
+    nowMinute: import("solid-js").Accessor<number>;
+    nowIn: (key: string) => number;
+    calendarToday: import("solid-js").Accessor<string>;
+    clock: (minute: number) => string;
+    duration: (minutes: number) => string;
+    instant: (key: string, minute: number) => Date;
+    normalized: (event: CalendarEvent, key: string) => NormalizedEvent;
+    checkedOf: (event: CalendarEvent) => boolean | undefined;
+    toggleCheck: (event: CalendarEvent) => void;
+    checkOf: (event: CalendarEvent) => (() => void) | undefined;
+    justChecked: import("solid-js").Accessor<ReadonlySet<string>>;
+    cheered: import("solid-js").Accessor<string | null>;
+    selection: import("solid-js").Accessor<TimeSelection | null>;
+    setSelection: import("solid-js").Setter<TimeSelection | null>;
+    touchDraft: import("solid-js").Accessor<{
+        key: string;
+        start: number;
+        end: number;
+    } | null>;
+    setTouchDraft: import("solid-js").Setter<{
+        key: string;
+        start: number;
+        end: number;
+    } | null>;
+    activeKey: import("solid-js").Accessor<string | null>;
+    setActiveKey: import("solid-js").Setter<string | null>;
+    ghost: import("solid-js").Accessor<Ghost | null>;
+    gapHit: import("solid-js").Accessor<{
+        key: string;
+        start: number;
+        fits: boolean;
+        text: string;
+    } | null>;
+    movingId: import("solid-js").Accessor<string>;
+    dragging: import("solid-js").Accessor<"" | "draw" | "end" | "external" | "move" | "start">;
+    nightOpen: (key: string, model: DayModel<CalendarEvent>) => boolean;
+    setNight: (key: string, open: boolean) => {
+        [x: string]: boolean;
+    };
+    quick: import("solid-js").Accessor<QuickCreate | null>;
+    setQuick: import("solid-js").Setter<QuickCreate | null>;
+    openQuickCreate: (key: string, start: number | undefined, end: number | undefined, anchor: Element | DOMRect, create?: string) => void;
+    canCreate: () => boolean;
+    createTarget: (visible: {
+        first: string;
+        last: string;
+    }) => {
+        key: string;
+        start: number;
+        end: number;
+    };
+    rangeOfSelection: (value: TimeSelection) => CalendarEventTimeChange;
+    registerBody: (key: string, element: HTMLElement, expanded: () => boolean) => void;
+    bodyAt: (clientX: number, clientY: number) => BodyHit | null;
+    limitOf: (key: string) => number;
+    startMove: (pointerEvent: PointerEvent, event: CalendarEvent, key: string, start: number, end: number, scroller?: HTMLElement) => void;
+    startResize: (pointerEvent: PointerEvent, event: CalendarEvent, key: string, start: number, end: number, edge: "start" | "end", scroller?: HTMLElement) => void;
+    startDraw: (pointerEvent: PointerEvent, key: string, scroller?: HTMLElement) => void;
+    dragIn: (pointerEvent: PointerEvent, item: CalendarExternalDrag, onDrop: (slot: CalendarEventTimeChange) => void, scroller?: HTMLElement) => void;
+    dayStartMinute: (hour: number) => number;
+};
+export type TimeView = ReturnType<typeof createTimeView>;
+/**
+ * German short dates read "Fr 9. Okt", without the dots of the abbreviations; with `comma`, a title such as
+ * "Fr, 9. Okt 2026" keeps the comma after the day.
+ */
+export declare const compactGermanDate: (text: string, locale: string | undefined, comma?: boolean) => string;
+/** A short day such as "Fri 9" or "Fr 9.", in the calendar's locale. */
+export declare const shortDay: (view: TimeView, key: string, withMonth?: boolean) => string;
+/** A long day such as "Friday, October 9", with the year when it is not this year's. */
+export declare const longDay: (view: TimeView, key: string) => string;
+/** A to-do's checkbox: it draws its check, and the title beside it strikes through. */
+export declare const TimeCheck: (props: {
+    view: TimeView;
+    event: CalendarEvent;
+    tabIndex?: number;
+}) => import("solid-js").JSX.Element;
+/** A timed entry in a day's timeline: a band as long as the entry, side by side with overlapping ones. */
+export declare const TimeBand: (props: {
+    view: TimeView;
+    band: DayLane<CalendarEvent>;
+    dayKey: string;
+    expanded: boolean;
+    compact?: boolean;
+    /** Day view: a tall band shows its place. */
+    showLocation?: boolean;
+    /** The height of an hour on a wide screen, for the band's size class and title lines. */
+    hourPx: number;
+    tabIndex?: number;
+    stop?: CalendarStop;
+    scroller?: () => HTMLElement | undefined;
+}) => import("solid-js").JSX.Element;
+/** A point in time such as a deadline: a dashed line across the day and a pill with its checkbox and title. */
+export declare const TimeMarker: (props: {
+    view: TimeView;
+    event: CalendarEvent;
+    minute: number;
+    dayKey: string;
+    expanded: boolean;
+    above: boolean;
+    /** The pill's place among deadlines whose pills would cover each other, from the left. */
+    lane: number;
+    lanes: number;
+    showTime: boolean;
+    tabIndex?: number;
+    stop?: CalendarStop;
+    scroller?: () => HTMLElement | undefined;
+}) => import("solid-js").JSX.Element;
+/** Free time between entries, labelled from an hour on; activating it creates there. */
+export declare const TimeGap: (props: {
+    view: TimeView;
+    gap: DayGap;
+    dayKey: string;
+    expanded: boolean;
+    /** A deadline pill near the middle moves the label aside. */
+    aside: boolean;
+    tabIndex?: number;
+    stop?: CalendarStop;
+}) => import("solid-js").JSX.Element;
+/** The preview of a drag, a draw, or an entry dragged in, and the selected slot. */
+export declare const TimeOverlays: (props: {
+    view: TimeView;
+    dayKey: string;
+    expanded: boolean;
+}) => import("solid-js").JSX.Element;
+/** Free time of a day with the gap of now trimmed, as both views draw it. */
+export declare const dayGaps: (view: TimeView, key: string) => DayGap[];
+/** The bands of a day with their lanes, cut to what its timeline draws. */
+export declare const dayBands: (view: TimeView, key: string, expanded: boolean) => DayLane<CalendarEvent>[];
+/** Entries the folded night hides, as chips with their time. */
+export declare const foldedEntries: (view: TimeView, key: string) => {
+    event: CalendarEvent;
+    time: string;
+}[];
+/** The quick create at a slot or gap, as in the month view. */
+export declare const TimeQuickCreate: (props: {
+    view: TimeView;
+}) => import("solid-js").JSX.Element;
+/** All-day entries of a day as chips: bars with torn ends where they go on, and points due that day. */
+export declare const AllDayChips: (props: {
+    view: TimeView;
+    dayKey: string;
+    spans: readonly DaySpan<CalendarEvent>[];
+}) => import("solid-js").JSX.Element;
+/** Hour labels and lines of a day's timeline with the night open, and the date at midnight. */
+export declare const nightHours: (wake: number) => number[];
+export declare const isNearNow: (view: TimeView, key: string, minute: number) => boolean;
+/** Whether a marker sits right above a band's start, so its pill goes above the line. */
+export declare const markerAbove: (model: DayModel<CalendarEvent>, minute: number) => boolean;
+/** Whether a deadline pill sits near the middle of a gap, so the gap's label moves aside. */
+export declare const gapAside: (model: DayModel<CalendarEvent>, gap: DayGap) => boolean;
+/** A day's counts for its header: events and all-day entries, to-dos and deadlines. */
+export declare const daySummary: (view: TimeView, key: string) => string;
+/** What starts within the next hour today, such as "Planning in 12 min". */
+export declare const soonNote: (view: TimeView, key: string) => string;
+/** The busy minutes of a day's waking hours, merged, with the color of the first entry, for the thin load line. */
+export declare const dayLoad: (view: TimeView, key: string) => {
+    start: number;
+    end: number;
+    color: string;
+}[];
+/** Day keys of the week that holds a day, from its first day. */
+export declare const weekKeysOf: (view: TimeView, key: string) => string[];
+export {};

package/dist/types/content/chart-messages.d.ts

@@ -14,6 +14,11 @@ declare const chartMessages: import("@k2b/stdlib").Catalog<{
     chartPreviousData: string;
     chartCopyData: string;
     chartCopyFailed: string;
+    chartLegend: string;
+    chartRowsShown: ({ shown, total }: {
+        shown: string;
+        total: string;
+    }) => string;
     interactiveLineChart: string;
     interactiveChart: string;
     chartFields: ({ key }: {

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

@@ -1,8 +1,8 @@
-export type { CalendarAttendee, CalendarCustomView, CalendarDayBadge, CalendarEvent, CalendarEventColor, CalendarEventRenderContext, CalendarEventTimeChange, CalendarLabels, CalendarProps, CalendarQuickCreateControls, CalendarRecurrence, CalendarResource, CalendarSelectionControls, CalendarView, } from "./Calendar";
+export type { CalendarAttendee, CalendarCommand, CalendarController, CalendarCustomView, CalendarDayBadge, CalendarEvent, CalendarEventColor, CalendarEventRenderContext, CalendarEventTimeChange, CalendarExternalDrag, CalendarLabels, CalendarProps, CalendarQuickCreateControls, CalendarRange, CalendarRecurrence, CalendarResource, CalendarSelectionControls, CalendarView, } from "./Calendar";
 export { default as Calendar } from "./Calendar";
 export type { ChartKind, ChartLabels, ChartProps, ChartRenderOptions } from "./Chart";
 export { default as Chart } from "./Chart";
-export type { ChartExplorerColumn, ChartExplorerProps } from "./ChartExplorer";
+export type { ChartExplorerColumn, ChartExplorerProps, ChartLegendEntry } from "./ChartExplorer";
 export { ChartExplorer } from "./ChartExplorer";
 export type { ChartExplorerControlsProps } from "./ChartExplorerControls";
 export { ChartExplorerControls } from "./ChartExplorerControls";

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

@@ -7,6 +7,8 @@ export type AppWorkspaceProps = {
     class?: string;
     /** A host with its own phone chrome can use the full canvas below 48rem (768 px). */
     mobileSurface?: "contained" | "flush";
+    /** Draws no frame: no border, corner radius, or shadow, for an overview that is the page itself. */
+    flat?: boolean;
     resizable?: boolean;
     /**
      * Restores a persisted layout when the workspace mounts. Persistence itself
@@ -77,8 +79,14 @@ export type AppWorkspaceDetailProps = {
      * overlaying it as a drawer.
      */
     onClose?: () => void;
-    /** Shows the previous (`-1`) or next (`1`) item; J and K call it while the panel is open. */
-    onStep?: (direction: 1 | -1) => void;
+    /**
+     * Shows the previous (`-1`) or next (`1`) item; J and K call it while the
+     * panel is open. Return the Main element that now shows the selection,
+     * usually its link: Escape and F6 then go there, and the workspace reveals
+     * it beside the panel or above the phone sheet. Returning nothing keeps the
+     * previous item.
+     */
+    onStep?: (direction: 1 | -1) => HTMLElement | null | undefined | void;
 };
 export type AppWorkspaceBottomDrawerHeight = "sm" | "md" | "lg";
 export type AppWorkspaceBottomDrawerProps = {
@@ -176,7 +184,12 @@ export type AppWorkspaceSidebarItemProps = {
     scroll?: NavigationScrollMode;
     onNavigate?: (event: LinkNavigateEvent) => void | Promise<void>;
     onClick?: (event: MouseEvent) => void;
-    active?: 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
+     * the highlight, and the page keeps its back link.
+     */
+    active?: boolean | "ancestor";
     activeClass?: string;
     disabled?: boolean;
     icon?: string;
@@ -256,6 +269,15 @@ export type AppWorkspaceSidebarItemStatusProps = {
     mention?: boolean;
     /** Shows a muted bell. */
     muted?: boolean;
+    /**
+     * Items that wait for the person, such as requests to approve, in the unread slot instead of `unread`. `label` is
+     * the phrase a screen reader hears, for example "3 waiting". `0` stays as a muted count, for a count that dropped
+     * to zero while the row is still shown; leave the prop out when nothing waits.
+     */
+    waiting?: {
+        count: number;
+        label: string;
+    };
 };
 export type AppWorkspaceNavTreeProps = {
     children: JSX.Element;

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

@@ -55,7 +55,8 @@ export declare const usePageTrail: () => (() => PageTrailState | undefined);
 export declare function PageTitle(props: PageTitleProps): JSX.Element;
 /**
  * Keeps server-rendered titles of the host's trail current: a workspace head
- * that never hydrates, and an app's own header title from the host's trail.
+ * that never hydrates, its heading, and an app's own header title from the
+ * host's trail.
  * When the host publishes a new trail, for example after `setPageTrail()`,
  * each such title is replaced in place by a live one with the same element,
  * class, and subtitle, and a head learns whether it now has a page above it.

package/dist/types/layout/app-workspace-controller.d.ts

@@ -11,6 +11,14 @@ export type AppWorkspaceControllerOptions = {
 export declare const APP_WORKSPACE_SIDEBAR_HIDE_EVENT = "k2b-app-workspace-sidebar-hide";
 /** Asks the owning `AppWorkspace.Detail` to close; its `onClose` decides. */
 export declare const APP_WORKSPACE_DETAIL_CLOSE_EVENT = "k2b-app-workspace-detail-close";
-/** Asks the owning `AppWorkspace.Detail` for the previous or next item, as `detail.direction` of `-1` or `1`. */
+/**
+ * Asks the owning Detail to step by `detail.direction` (`-1` or `1`). It writes
+ * the Main element showing the selection to `detail.item`, read synchronously
+ * by the controller after dispatch.
+ */
 export declare const APP_WORKSPACE_DETAIL_STEP_EVENT = "k2b-app-workspace-detail-step";
+export type AppWorkspaceDetailStep = {
+    direction: 1 | -1;
+    item?: HTMLElement;
+};
 export declare const installAppWorkspaceController: (options?: AppWorkspaceControllerOptions) => (() => void);

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

@@ -17,6 +17,11 @@ export type StatCellProps = {
     title?: string;
     trend?: readonly number[];
     size?: StatGridSize;
+    /**
+     * 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;
 };
 export declare function StatCell(props: StatCellProps): JSX.Element;
 export default StatCell;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/ui",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Production-ready components for SolidJS applications.",
   "repository": {
     "type": "git",