@arbidocs/blocks 0.3.184 → 0.4.0

package/dist/studio/liveData.d.ts

@@ -0,0 +1,4 @@
+/** True only where live widgets may resolve backend data (an authenticated app tree). */
+export declare const LiveDataContext: import("react").Context<boolean>;
+/** Whether live widgets may resolve backend data here (false in editor/public). */
+export declare function useLiveDataActive(): boolean;

package/dist/studio/liveWidgetRuntime.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Live-widget runtime: everything in the seam that RENDERS — the provider that
+ * turns the live-data gate on for an authenticated app tree, the placeholder
+ * shown everywhere else, and the widget block bodies themselves (each gates on
+ * the live-data flag and renders live data or a placeholder).
+ *
+ * Components only — kept apart from the context/hook ({@link ./liveData}) and the
+ * config factory ({@link ./widgets}) so every file in the seam is fast-refresh
+ * clean (a file exports either components or non-components, never both, and a
+ * non-component-export file defines no components).
+ *
+ * The widgets read the SHARED `@arbidocs/react` hooks and the package connection
+ * (for the active workspace), so they are host-agnostic.
+ */
+import type { LucideIcon } from 'lucide-react';
+import type { ReactNode } from 'react';
+/** Marks the subtree as an authenticated app tree, so live widgets resolve data. */
+export declare function LiveDataProvider({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * What a live widget shows when it can't (or shouldn't) resolve data: a labelled,
+ * dashed card. Used in the Studio canvas and the public renderer so authoring a
+ * dashboard is WYSIWYG-ish without leaking live back-office data.
+ */
+export declare function WidgetPlaceholder({ label, icon: Icon, testId, }: {
+    label: string;
+    icon?: LucideIcon;
+    testId?: string;
+}): import("react").JSX.Element;
+export declare function AgentActivityBlock({ title, limit, testId, }: {
+    title: string;
+    limit: number;
+    testId: string;
+}): import("react").JSX.Element;
+export declare function LiveMetricBlock({ label, source, accent, testId, }: {
+    label: string;
+    source: string;
+    accent: string;
+    testId: string;
+}): import("react").JSX.Element;

package/dist/studio/persistence.d.ts

@@ -0,0 +1,38 @@
+import type { StudioPersistence } from './types';
+/** Thrown instead of silently degrading to plaintext local storage. */
+export declare class StudioPersistenceError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * - `off` (default): never touch localStorage; ARBI failures reject.
+ * - `fallback`: use localStorage only when ARBI is unavailable or fails.
+ * - `always`: additionally mirror every successful ARBI save locally.
+ */
+export type StudioLocalStorageMode = 'off' | 'fallback' | 'always';
+export interface StudioPersistenceConfig {
+    /** The public marketing workspace that backs the site builder. */
+    workspaceId: string;
+    /** Folder inside the workspace where studio artefacts live. */
+    folder?: string;
+    /** Prefix for the localStorage keys (e.g. "studio-"); only used when local storage is on. */
+    storagePrefix: string;
+    /** Opt-in plaintext local storage (default "off"). */
+    localStorageMode?: StudioLocalStorageMode;
+    /**
+     * Isolation scope inserted into every local key, evaluated per call so it follows the
+     * current user and workspace (e.g. `${userId}:${workspaceId}`). Required when
+     * `localStorageMode` is not "off"; without a scope local access rejects.
+     */
+    storageScope?: () => string | null | undefined;
+    /** localStorage key for the theme mirror (default `${storagePrefix}theme`). */
+    themeStorageKey?: string;
+    /** File name for the persisted theme document (default "theme.json"). */
+    themeFileName?: string;
+    /** File name for a page's persisted document (default `${slug}.json`). */
+    pageFileName?: (slug: string) => string;
+    /** File name for a page's published document (default `${slug}.published.json`). */
+    publishedFileName?: (slug: string) => string;
+}
+export declare function createStudioPersistence(cfg: StudioPersistenceConfig): StudioPersistence;

package/dist/studio/publish.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Publish-time asset materialization.
+ *
+ * While authoring, an image is stored as a workspace **asset ref**
+ * (`asset:<docId>`) — resolvable only inside the authenticated Studio. The
+ * public marketing renderer has no auth token, so a published page must be
+ * **self-contained**: every asset ref is replaced with a directly-renderable
+ * source before the page is saved for the public.
+ *
+ * The default {@link createArbiMaterializer} downloads each asset once and
+ * inlines it as a `data:` URI — the bytes travel *inside* the published JSON,
+ * so nothing is fetched, served or auth-gated at render time (no backend). A
+ * consumer that prefers a CDN/static host can pass a `publishAsset` hook that
+ * uploads the bytes and returns a URL instead; that is purely a payload-size
+ * optimization and keeps this package host- and backend-agnostic.
+ */
+import type { Data } from '@measured/puck';
+import type { Arbi } from './types';
+/** Resolve a workspace document ext_id to a public-renderable src, or null. */
+export type AssetMaterializer = (docId: string) => Promise<string | null>;
+export interface MaterializeOptions {
+    /**
+     * Optional sink: given a doc id + its bytes, store them somewhere public and
+     * return the URL. When omitted, bytes are inlined as a `data:` URI (no backend).
+     */
+    publishAsset?: (docId: string, blob: Blob) => Promise<string>;
+}
+/**
+ * A materializer backed by the authenticated Arbi client: download the asset,
+ * then either hand it to `publishAsset` or inline it as a data URI. Any failure
+ * resolves to `null` so a single broken asset never fails the whole publish.
+ */
+export declare function createArbiMaterializer(arbi: Arbi, opts?: MaterializeOptions): AssetMaterializer;
+/**
+ * Return a copy of `data` with every `asset:<docId>` ref replaced by its
+ * materialized source. Each distinct ref is resolved exactly once; a ref that
+ * fails to resolve is left untouched (it simply won't paint for the public).
+ */
+export declare function materializePageData(data: Data, materialize: AssetMaterializer): Promise<Data>;

package/dist/studio/siteBlocks.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The extended site-building block set — the richer vocabulary a builder needs to
+ * assemble arbitrary sites beyond the marketing basics: pricing, tabs, accordion,
+ * gallery, video, contact form, banner, split media, team, steps and a
+ * multi-testimonial grid.
+ *
+ * Same contract as {@link createWebsiteBlocks}: serializable-only props, semantic
+ * tokens (themes with the host), a stable render-time `data-testid`, and sensible
+ * defaults so each block looks right the moment it is dropped. Copy props route
+ * through the shared {@link BlockKit} AI-or-plain fields.
+ */
+import type { ComponentConfig } from '@measured/puck';
+import type { BlockKit } from './blockKit';
+export declare function createSiteBlocks(kit: BlockKit): Record<string, ComponentConfig>;

package/dist/studio/types.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared studio types — the persistence contract, page metadata and the AI
+ * prompt-builder signature the host supplies. Firm-agnostic: a host app wires
+ * these to its own marketing workspace and voice.
+ */
+import type { useArbi } from '@arbidocs/react';
+/** The Arbi instance type, borrowed from the hook so we don't import internals. */
+export type Arbi = ReturnType<typeof useArbi>;
+/** A page the studio can author (slug → friendly label). */
+export interface StudioPageMeta {
+    slug: string;
+    label: string;
+}
+/** Where a save/load ultimately resolved. */
+export type PersistVia = 'arbi' | 'local';
+export interface LoadResult<T> {
+    data: T | null;
+    via: PersistVia;
+}
+/** The save/load surface the studio + renderer consume. */
+export interface StudioPersistence {
+    /** Persist the authoring layout for a slug (image values stay `asset:` refs). */
+    savePage: (arbi: Arbi | null, live: boolean, slug: string, data: unknown) => Promise<PersistVia>;
+    loadPage: <T>(arbi: Arbi | null, live: boolean, slug: string) => Promise<LoadResult<T>>;
+    /**
+     * Persist the **published** layout for a slug — a self-contained copy whose
+     * asset refs have been materialized to `data:` URIs, so the unauthenticated
+     * public renderer can paint it. The public renderer reads this, not savePage's.
+     */
+    savePublished: (arbi: Arbi | null, live: boolean, slug: string, data: unknown) => Promise<PersistVia>;
+    loadPublished: <T>(arbi: Arbi | null, live: boolean, slug: string) => Promise<LoadResult<T>>;
+    /**
+     * Delete a slug's stored authoring + published pages (backend and localStorage
+     * mirror). Lets a page be reset to empty; also the deterministic-reset hook a
+     * test/demo needs, since backend content otherwise wins over a fresh seed.
+     */
+    deletePage: (arbi: Arbi | null, live: boolean, slug: string) => Promise<void>;
+    saveTheme: (arbi: Arbi | null, live: boolean, theme: unknown) => Promise<PersistVia>;
+    loadTheme: <T>(arbi: Arbi | null, live: boolean) => Promise<LoadResult<T>>;
+}
+/** Build an AI instruction for a field, given its kind, label and current text. */
+export type BuildPrompt = (a: {
+    kind: string;
+    label: string;
+    current: string;
+}) => string;

package/dist/studio/websiteBlocks.d.ts

@@ -0,0 +1,4 @@
+import type { ComponentConfig } from '@measured/puck';
+import type { BlockKit } from './blockKit';
+/** Build every website block, closing over the shared field {@link BlockKit}. */
+export declare function createWebsiteBlocks(kit: BlockKit): Record<string, ComponentConfig>;

package/dist/studio/widgets.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Live-widget block factory for @arbidocs/blocks.
+ *
+ * Mirrors the other `create*Blocks` factories: it only WIRES pre-built block
+ * components (from {@link ./liveWidgetRuntime}) into Puck `ComponentConfig`s, so
+ * it exports a single function and defines no components of its own — keeping it
+ * fast-refresh clean. The blocks gate on the live-data flag ({@link ./liveData}),
+ * rendering real ARBI data inside an authenticated app tree and a placeholder in
+ * the editor/public. They read the SHARED `@arbidocs/react` hooks, so any client
+ * with an ARBI workspace gets them; a client supplies only *composition* via
+ * `createArbiBlocksConfig({ liveWidgets: true })`.
+ */
+import type { ComponentConfig } from '@measured/puck';
+import type { BlockKit } from './blockKit';
+/**
+ * Build the live-widget block set, closing over the shared {@link BlockKit} for
+ * stable testids. Registered under a "Widgets" category when a consumer opts in
+ * with `createArbiBlocksConfig({ liveWidgets: true })`.
+ */
+export declare function createLiveWidgets(kit: BlockKit): Record<string, ComponentConfig>;

package/dist/theme/ThemeEditor.d.ts

@@ -0,0 +1,16 @@
+import type { ThemeBundle } from './store';
+export interface ThemeEditorProps {
+    /** The host's theme store bundle (from createThemeStore). */
+    bundle: ThemeBundle;
+    variant?: 'panel' | 'drawer';
+    /** Firm identity shown in the panel's live-preview header. */
+    preview?: {
+        title: string;
+        subtitle?: string;
+    };
+    /** Optional persistence side-channel (e.g. save theme to ARBI); returns a "via" label. */
+    onSave?: () => Promise<string | void>;
+    /** Stable testid namespace, e.g. "builder-theme" | "studio-theme". */
+    testIdPrefix?: string;
+}
+export declare function ThemeEditor({ bundle, variant, preview, onSave, testIdPrefix, }: ThemeEditorProps): import("react").JSX.Element;

package/dist/theme/fontPairings.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Curated typography pairings — the choice a user actually makes.
+ *
+ * A pairing is a display face + a body face that are known to sit well together,
+ * so picking typography means picking a *look*, not authoring two CSS font
+ * stacks. The raw stacks remain editable for power users.
+ *
+ * DATA ONLY. This module names families; it never loads them, so the kit takes no
+ * font dependency. Web fonts are self-hosted per app (`@fontsource-variable/*`
+ * imported from the app's entry or stylesheet); `fontPackages()` reports exactly
+ * which packages a set of pairings needs. A pairing whose family an app has not
+ * imported does not error — it falls back down its own stack — so an app that
+ * offers a pairing must also ship its fonts.
+ */
+export interface FontPairing {
+    id: string;
+    /** Shown in the picker, e.g. "Newsreader / Inter". */
+    label: string;
+    /** One line on the character of the pairing. */
+    description: string;
+    /** Font stack for headings (`--font-display`). */
+    display: string;
+    /** Font stack for body copy (`--font-sans`). */
+    sans: string;
+    /**
+     * The npm packages an app must install + import to actually render this
+     * pairing, e.g. `['@fontsource-variable/inter']`. Empty when the pairing uses
+     * only system faces.
+     */
+    packages: string[];
+}
+/**
+ * The shipped catalog. Every entry uses variable fonts (one file per family)
+ * rather than per-weight static files.
+ */
+export declare const FONT_PAIRINGS: FontPairing[];
+/** Look a pairing up by id. Returns undefined for an unknown id. */
+export declare function getFontPairing(id: string): FontPairing | undefined;
+/**
+ * The pairing whose stacks match `fonts`, or undefined when the stacks have been
+ * hand-edited away from every preset. Lets a picker show "Custom" honestly.
+ */
+export declare function matchFontPairing(fonts: {
+    display: string;
+    sans: string;
+}): FontPairing | undefined;
+/** Every npm package needed to render the given pairings (deduped). */
+export declare function fontPackages(pairings?: FontPairing[]): string[];

package/dist/theme/store.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The shared theme store factory. A host calls {@link createThemeStore} once
+ * with its token catalog, default values and presets; the returned bundle (a
+ * zustand hook + metadata) is the single source of truth consumed by every
+ * theme surface (the back-office builder panel and the studio drawer), so the
+ * token model, presets and apply logic live in exactly one place.
+ */
+import { type UseBoundStore, type StoreApi } from 'zustand';
+import { type ColorToken, type ThemeEmitMode, type ThemeFonts, type ThemePreset, type ThemeTokens } from './tokens';
+export interface ThemeState extends ThemeTokens {
+    activePresetId: string | null;
+    setColor: (key: string, value: string) => void;
+    setFont: (which: keyof ThemeFonts, value: string) => void;
+    /** Apply a curated pairing, setting the display and body faces together. */
+    setFontPairing: (pairingId: string) => void;
+    setRadius: (radius: number) => void;
+    applyPreset: (presetId: string) => void;
+    reset: () => void;
+    /** Snapshot of the editable tokens (for export / live apply). */
+    snapshot: () => ThemeTokens;
+}
+export interface ThemeStoreConfig {
+    /** The editable token catalog (keys + labels + groups). */
+    tokens: ColorToken[];
+    /** Group id → heading, for the grouped panel layout. */
+    groupLabels: Record<string, string>;
+    /** Shipped defaults (the host's brand values). */
+    defaultTheme: ThemeTokens;
+    /** Starting points the user can apply then fine-tune. */
+    presets: ThemePreset[];
+    /** localStorage key for persistence (namespaced per host). */
+    storageKey: string;
+    /**
+     * How edits are written onto the document. Defaults to `'flat'` (inline
+     * `--color-*`). `'cssVars'` emits raw HSL-triplet vars into an injected
+     * `<style>` so an app's own `hsl(var(--x))` indirection + `.dark` variant
+     * survive. See {@link applyThemeVars}.
+     */
+    mode?: ThemeEmitMode;
+    /**
+     * `cssVars` mode only: the dark-variant colour values keyed by token key,
+     * emitted under `:root.dark`. Required (per editable token) for any host with a
+     * dark mode, otherwise a light-token override leaks into dark.
+     */
+    darkColors?: Record<string, string>;
+}
+export interface ThemeBundle extends ThemeStoreConfig {
+    useStore: UseBoundStore<StoreApi<ThemeState>>;
+}
+/** Build a brand-specific theme store bundle. */
+export declare function createThemeStore(config: ThemeStoreConfig): ThemeBundle;
+/** Apply a bundle's current store to the live document, honouring its emit mode. */
+export declare function applyStoredTheme(bundle: ThemeBundle): void;

package/dist/theme/tokens.d.ts

@@ -0,0 +1,105 @@
+/**
+ * The theme-token model. Firm-agnostic: the token *catalog*, default values and
+ * presets are supplied by the consuming app (via {@link createThemeStore}); this
+ * module owns the shared types and the logic for writing tokens onto the live
+ * document.
+ *
+ * There are two emit models, selected per-app by {@link ThemeEmitMode}:
+ *
+ * - `'flat'` (default): each colour key is written as an inline `--color-<key>`
+ *   custom property on `<html>`, plus `--font-*` / `--radius`. Inline styles
+ *   override the compiled `@theme` defaults, so an edit previews live across the
+ *   whole app (and the @arbidocs AI kit) and reverts cleanly. Apps whose CSS sets
+ *   `--color-*` HEX directly rely on this.
+ *
+ * - `'cssVars'`: each colour key is written as a raw
+ *   HSL-triplet custom property (`--<key>: <h s l>`) into an injected
+ *   `<style id="arbi-theme-vars">` appended to `<head>`. The monolith's source
+ *   of truth is HSL triplets wrapped as `hsl(var(--x))`, with a real `.dark`
+ *   variant; writing resolved hex inline would pin the colour and defeat both
+ *   the indirection and the dark-class swap. The injected sheet is *unlayered*,
+ *   so it wins over the monolith's `@layer base` `colors.css` at equal
+ *   specificity, and a `:root { light } / :root.dark { dark }` structure keeps
+ *   the dark cascade alive.
+ */
+export interface ColorToken {
+    /** Key without the `--color-` prefix, e.g. "primary" → `--color-primary`. */
+    key: string;
+    label: string;
+    /** Grouping id for the panel layout (e.g. "shadcn" | "brand" | "ai"). */
+    group: string;
+}
+export interface ThemeFonts {
+    display: string;
+    sans: string;
+}
+export interface ThemeTokens {
+    /** Colour values keyed by token key (hex). */
+    colors: Record<string, string>;
+    fonts: ThemeFonts;
+    /** Base radius in rem. */
+    radius: number;
+}
+export interface ThemePreset {
+    id: string;
+    label: string;
+    tokens: ThemeTokens;
+}
+/** How a theme is written onto the document. See the module doc for the models. */
+export type ThemeEmitMode = 'flat' | 'cssVars';
+export interface ApplyThemeOptions {
+    /** Emit model. Defaults to `'flat'`. */
+    mode?: ThemeEmitMode;
+    /**
+     * `cssVars` mode only: dark-variant colour values keyed by token key. Emitted
+     * under `:root.dark`. When omitted, only `:root` is emitted — note that an
+     * overridden light token then also applies in dark (the injected `:root` is
+     * unlayered and beats the app's own `.dark` rules), so a host with a dark mode
+     * MUST supply this for every editable token to keep dark mode intact.
+     */
+    dark?: Record<string, string>;
+    /** `flat` mode only: target element. Defaults to `document.documentElement`. */
+    root?: HTMLElement;
+}
+/** Id of the injected `<style>` that carries the `cssVars`-mode custom properties. */
+export declare const THEME_STYLE_ID = "arbi-theme-vars";
+/**
+ * Convert a colour to the monolith's `H S% L%` HSL-triplet format.
+ *
+ * Handles `#rgb` / `#rrggbb`, `rgb()` / `rgba()`, and passes an existing triplet
+ * through untouched (so a host can seed exact `colors.css` triplets for a
+ * byte-identical no-op). Values it cannot parse — notably `oklch(...)`, which the
+ * status tokens use — are returned unchanged so they remain usable as a raw
+ * custom-property value; converting those cleanly is out of scope.
+ */
+export declare function toHslTriplet(color: string): string;
+/**
+ * Write a theme onto the live document.
+ *
+ * In `flat` mode (default) writes inline `--color-<key>` / `--font-*` / `--radius`
+ * on `document.documentElement` (or a supplied root). In `cssVars` mode writes
+ * raw HSL-triplet vars into an injected `<style#arbi-theme-vars>` (see the module
+ * doc). The legacy `applyThemeVars(theme, rootElement)` call form still works.
+ */
+export declare function applyThemeVars(theme: ThemeTokens, optionsOrRoot?: ApplyThemeOptions | HTMLElement): void;
+/**
+ * Set ONLY the typography vars, as inline styles on the root element.
+ *
+ * Typography is often chosen independently of colour — an app may let a reader
+ * pick a typeface while its palette is owned elsewhere. Writing the two vars
+ * inline (rather than through `applyThemeVars`) keeps this orthogonal in two
+ * ways: it touches no colour or radius token, and an inline style outranks any
+ * selector, so a font choice survives a `cssVars`-mode theme that emits its own
+ * `:root` block (the ARBI studio's theme editor does exactly that).
+ */
+export declare function applyFontVars(fonts: ThemeFonts, root?: HTMLElement): void;
+/** Undo {@link applyFontVars}, reverting to the stylesheet's own font tokens. */
+export declare function clearFontVars(root?: HTMLElement): void;
+/**
+ * Remove a theme's overrides, reverting to the stylesheet defaults.
+ *
+ * In `flat` mode removes the inline overrides for the theme's keys. In `cssVars`
+ * mode removes the injected `<style#arbi-theme-vars>` in full (restoring the
+ * app's own `colors.css` exactly).
+ */
+export declare function clearThemeVars(theme: ThemeTokens, optionsOrRoot?: ApplyThemeOptions | HTMLElement): void;

package/dist/timeline/Timeline.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A timeline you can drop anywhere: the same items, seen as a calendar or as a
+ * Gantt, with a toggle between them.
+ *
+ * The two views answer different questions — a calendar says "what falls in this
+ * week", a Gantt says "how long did this run and what overlapped it" — and both
+ * read the identical {@link TimelineItem} array, so a host renders one component
+ * and lets the reader choose. Fix `view` to pin it to one.
+ */
+import { type ReactNode } from 'react';
+import type { TimelineItem } from './types';
+export type TimelineViewMode = 'calendar' | 'gantt';
+export interface TimelineProps<T extends TimelineItem = TimelineItem> {
+    items: T[];
+    /** Pin the view. Omit to show the toggle and let the reader switch. */
+    view?: TimelineViewMode;
+    /** Which view the toggle starts on. */
+    defaultView?: TimelineViewMode;
+    onSelect?: (item: T) => void;
+    /** Extra Gantt detail-panel content — sources, links, actions. */
+    renderDetail?: (item: T) => ReactNode;
+    /** Shown when nothing carries a date. */
+    emptyMessage?: string;
+    className?: string;
+    testId?: string;
+}
+export declare function Timeline<T extends TimelineItem = TimelineItem>({ items, view, defaultView, onSelect, renderDetail, emptyMessage, className, testId, }: TimelineProps<T>): import("react").JSX.Element;

package/dist/timeline/TimelineCalendar.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Continuous calendar over dated items.
+ *
+ * An item is a span, so one dated "October 2019" genuinely occupies every day of
+ * October. Repeating its label in all 31 cells is unreadable, so a multi-day item
+ * renders as ONE continuous bar spanning its days, broken only where a week ends
+ * — the label appears once, on the segment where the item starts.
+ *
+ * Segments are packed into lanes so overlapping items stack rather than collide,
+ * which is what makes a dense month legible.
+ *
+ * It scrolls as one unbroken run of weeks from the earliest item to the latest,
+ * rather than paging month by month: a chronology is read by moving along it, and
+ * paging hides exactly the thing you want to see — what sits on either side of a
+ * boundary. Month names mark where they change, and weeks stay whole, so days
+ * belonging to the neighbouring month simply appear dimmed.
+ *
+ * Everything reads the UTC components and never localises: a day-precision item
+ * stored at 00:00Z would otherwise land on the previous day for viewers west of
+ * UTC.
+ */
+import { type ReactNode } from 'react';
+import type { TimelineItem } from './types';
+export interface TimelineCalendarProps<T extends TimelineItem = TimelineItem> {
+    items: T[];
+    /** Clicking a bar. The caller's own object comes back, not a copy. */
+    onSelect?: (item: T) => void;
+    /** Bars shown per week before the remainder collapses to "+n more". */
+    maxLanes?: number;
+    /** Ids to treat as the current selection — positions the event navigator's
+     *  ‹ n / N › on the matching event (e.g. the one open in the app's editor). */
+    selectedIds?: readonly string[];
+    /**
+     * Where the ‹ n / N › event navigator renders. Omit it for the built-in
+     * inline placement. Pass a host element (e.g. a slot in the app's own
+     * toolbar) to portal the navigator there instead — or `null` while that slot
+     * isn't mounted yet, which renders no navigator at all rather than falling
+     * back inline (avoids a flash of the inline one on first paint).
+     */
+    navigatorContainer?: HTMLElement | null;
+    /**
+     * Denominator shown by the navigator (`n / N`). Defaults to the number of
+     * dated items it can step through; a host may pass its full (filtered) item
+     * count instead so the figure matches the list it shows elsewhere, even when
+     * some of those items carry no date and so never appear here.
+     */
+    navigatorTotal?: number;
+    /** Shown when nothing in `items` carries a date. */
+    emptyState?: ReactNode;
+    className?: string;
+    /** Prefix for every `data-testid` this view emits. */
+    testId?: string;
+}
+export declare function TimelineCalendar<T extends TimelineItem = TimelineItem>({ items, onSelect, selectedIds, maxLanes, navigatorContainer, navigatorTotal, emptyState, className, testId, }: TimelineCalendarProps<T>): import("react").JSX.Element;

package/dist/timeline/TimelineGantt.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Gantt view over dated items — one swimlane per item on a shared date axis.
+ *
+ * The axis is what makes it readable: bars are positioned by real elapsed time,
+ * so a span's WIDTH is its duration and an imprecise date shows AS imprecision —
+ * an item dated "2019" is a year-wide bar, an emailed one a hairline tick.
+ *
+ * Rows are sorted chronologically here rather than left to the caller: this is a
+ * chronology, and a caller handing over rows in creation order (newest first, as
+ * a notes list does) would render the timeline backwards.
+ *
+ * Selecting a bar opens the detail panel. The panel owns the parts every caller
+ * has — label, span, description — and hands the rest to `renderDetail`, which is
+ * where an app adds its own context (source documents, an owner, a link).
+ */
+import { type ReactNode } from 'react';
+import type { TimelineItem } from './types';
+export interface TimelineGanttProps<T extends TimelineItem = TimelineItem> {
+    items: T[];
+    /** The selected item, or null when the panel closes. */
+    onSelect?: (item: T | null) => void;
+    /**
+     * Ids to render as selected — e.g. rows a user checked in another view.
+     * Their bar and label are highlighted so the selection carries across views;
+     * this does not open the detail panel (that stays driven by clicks here).
+     */
+    selectedIds?: readonly string[];
+    /** Extra detail-panel content for the selected item — sources, links, actions. */
+    renderDetail?: (item: T) => ReactNode;
+    /** Width of the row-label gutter, in pixels. */
+    labelWidth?: number;
+    /**
+     * When provided, the label gutter becomes user-resizable: a drag handle
+     * appears on its right edge and this fires with the new width (px) as the
+     * user drags. The caller owns the value (so it can persist it) and feeds it
+     * back via `labelWidth`.
+     */
+    onLabelWidthChange?: (width: number) => void;
+    /** Clamp for the resizable gutter, in pixels. */
+    minLabelWidth?: number;
+    maxLabelWidth?: number;
+    /**
+     * Controlled date-axis zoom (1 = fit). Provide BOTH `zoom` and `onZoomChange`
+     * to drive it from outside — e.g. a button in the app's own header — which also
+     * suppresses the chart's built-in corner control. Omit them to use the internal
+     * state and the corner control.
+     */
+    zoom?: number;
+    onZoomChange?: (zoom: number) => void;
+    /**
+     * Where the ‹ n / N › event navigator renders. Omit it for the built-in
+     * inline placement. Pass a host element (e.g. a slot in the app's own
+     * toolbar) to portal the navigator there instead — or `null` while that slot
+     * isn't mounted yet, which renders no navigator at all rather than falling
+     * back inline (avoids a flash of the inline one on first paint).
+     */
+    navigatorContainer?: HTMLElement | null;
+    /**
+     * Denominator shown by the navigator (`n / N`). Defaults to the number of
+     * dated items it can step through; a host may pass its full (filtered) item
+     * count instead so the figure matches the list it shows elsewhere, even when
+     * some of those items carry no date and so never appear here.
+     */
+    navigatorTotal?: number;
+    /** Shown when nothing in `items` carries a usable date. */
+    emptyMessage?: string;
+    className?: string;
+    /** Prefix for every `data-testid` this view emits. */
+    testId?: string;
+}
+export declare function TimelineGantt<T extends TimelineItem = TimelineItem>({ items, onSelect, selectedIds, renderDetail, labelWidth, onLabelWidthChange, minLabelWidth, maxLabelWidth, zoom: zoomProp, onZoomChange, navigatorContainer, navigatorTotal, emptyMessage, className, testId, }: TimelineGanttProps<T>): import("react").JSX.Element;

package/dist/timeline/TimelineZoomControl.d.ts

@@ -0,0 +1,17 @@
+/** Zoom bounds shared by the control and the chart, so a hoisted control stays in
+ *  step with the plot scaling. STEP is the slider granularity. */
+export declare const TIMELINE_ZOOM: {
+    readonly MIN: 1;
+    readonly MAX: 10;
+    readonly STEP: 0.25;
+};
+export interface TimelineZoomControlProps {
+    /** Current zoom factor (1 = fit). */
+    zoom: number;
+    /** Fired with the next clamped zoom factor. */
+    onZoomChange: (zoom: number) => void;
+    className?: string;
+    /** Prefix for the `data-testid`s this control emits. */
+    testId?: string;
+}
+export declare function TimelineZoomControl({ zoom, onZoomChange, className, testId, }: TimelineZoomControlProps): import("react").JSX.Element;