@ripple-ui/svelte 0.0.0-stage → 0.8.2

package/dist/widgets/data/VirtualList.svelte

@@ -0,0 +1,137 @@
+<!-- src/lib/widgets/data/VirtualList.svelte
+     Virtualized list: only the rows in the scroll window (plus overscan) mount.
+     Rows are fixed-height (itemHeight). Default rows show `label` (or `name`)
+     with an optional muted `description` line, a hairline divider and a hover
+     fill. Without an explicit `height` the box hugs its content up to 320px,
+     so three items do not leave an empty slab. An empty list is one quiet
+     muted line with no frame. role="option" rows carry
+     aria-selected="false" (required ARIA prop). -->
+<script lang="ts">
+  import { safeStyle } from '@ripple-ui/core';
+  import type { Snippet } from 'svelte';
+  import { cn } from '../../utils.js';
+  import { safeArray } from '../../utils/safe-props.js';
+  import NodeRenderer from '../../components/NodeRenderer.svelte';
+
+  interface Props {
+    id?: string;
+    class?: string;
+    style?: Record<string, string>;
+    items?: unknown[];
+    /** Fixed row height in pixels. */
+    itemHeight?: number;
+    /** Container height (e.g. "320px" or 320 for px). */
+    height?: string | number;
+    /** Extra rows rendered above/below the visible window. */
+    overscan?: number;
+    /** Per-item template — receives `item` and `index` in loop context. */
+    item?: any;
+    emptyText?: string;
+    children?: Snippet;
+  }
+
+  let {
+    id,
+    class: className,
+    style,
+    items: rawItems = [],
+    itemHeight: rawItemHeight,
+    height,
+    overscan = 5,
+    item,
+    emptyText = 'No items',
+    children
+  }: Props = $props();
+
+  const items = $derived(safeArray(rawItems, { widget: 'virtual-list', key: 'items' }));
+
+  const styleString = $derived(
+    style ? Object.entries(style).map(([k, v]) => `${k}:${v}`).join(';') : undefined
+  );
+
+  const field = (v: unknown, k: string): unknown =>
+    v != null && typeof v === 'object' ? (v as Record<string, unknown>)[k] : undefined;
+  const hasDescriptions = $derived(items.some((v) => field(v, 'description') != null));
+  const itemHeight = $derived(
+    typeof rawItemHeight === 'number' && rawItemHeight > 0 ? rawItemHeight : hasDescriptions ? 52 : 36
+  );
+
+  const containerHeight = $derived(
+    height != null && height !== ''
+      ? typeof height === 'number' ? `${height}px` : height
+      : `${items.length === 0 ? 120 : items.length * itemHeight}px; max-height: 320px`
+  );
+
+  let scrollTop = $state(0);
+  let viewportHeight = $state(320);
+  let viewportEl = $state<HTMLDivElement | null>(null);
+
+  $effect(() => {
+    if (!viewportEl) return;
+    viewportHeight = viewportEl.clientHeight;
+    if (typeof ResizeObserver === 'undefined') return;
+    const ro = new ResizeObserver(() => {
+      viewportHeight = viewportEl?.clientHeight ?? 0;
+    });
+    ro.observe(viewportEl);
+    return () => ro.disconnect();
+  });
+
+  const total = $derived(items.length);
+  const totalHeight = $derived(total * itemHeight);
+
+  const start = $derived(Math.max(0, Math.floor(scrollTop / itemHeight) - overscan));
+  const visibleCount = $derived(Math.ceil(viewportHeight / itemHeight) + overscan * 2);
+  const end = $derived(Math.min(total, start + visibleCount));
+
+  const visible = $derived.by(() => {
+    const out: { item: unknown; index: number }[] = [];
+    for (let i = start; i < end; i++) out.push({ item: items[i], index: i });
+    return out;
+  });
+
+  const offsetY = $derived(start * itemHeight);
+
+  function onScroll(e: Event) {
+    scrollTop = (e.target as HTMLDivElement).scrollTop;
+  }
+
+  function isSpec(v: unknown): boolean {
+    return v != null && typeof v === 'object' && !Array.isArray(v) && typeof (v as any).type === 'string';
+  }
+</script>
+
+<div
+  {id}
+  bind:this={viewportEl}
+  onscroll={onScroll}
+  class={cn('relative overflow-auto', total > 0 && 'rounded-md border border-border', className)}
+  style={safeStyle(`height: ${total === 0 ? 'auto' : containerHeight}; ${styleString ?? ''}`)}
+  role="listbox"
+>
+  {#if total === 0}
+    <div class="py-2 text-sm text-muted-foreground">{emptyText}</div>
+  {:else}
+    <div style={safeStyle(`height: ${totalHeight}px; position: relative;`)}>
+      <div style={safeStyle(`position: absolute; top: 0; left: 0; right: 0; transform: translateY(${offsetY}px);`)}>
+        {#each visible as v (v.index)}
+          <div class="border-b border-border/70 last:border-b-0 hover:bg-muted/50 transition-colors" style={safeStyle(`height: ${itemHeight}px;`)} role="option" aria-selected="false" aria-posinset={v.index + 1} aria-setsize={total}>
+            {#if isSpec(item)}
+              <NodeRenderer node={item} loopContext={{ item: v.item, index: v.index }} />
+            {:else if children}
+              {@render children()}
+            {:else}
+              {@const desc = field(v.item, 'description')}
+              <div class="flex h-full min-w-0 flex-col justify-center px-3">
+                <div class="truncate text-sm font-medium">{String(field(v.item, 'label') ?? field(v.item, 'name') ?? v.item)}</div>
+                {#if desc != null}
+                  <div class="truncate text-xs text-muted-foreground">{String(desc)}</div>
+                {/if}
+              </div>
+            {/if}
+          </div>
+        {/each}
+      </div>
+    </div>
+  {/if}
+</div>

package/dist/widgets/data/VirtualList.svelte.d.ts

@@ -0,0 +1,20 @@
+import type { Snippet } from 'svelte';
+interface Props {
+    id?: string;
+    class?: string;
+    style?: Record<string, string>;
+    items?: unknown[];
+    /** Fixed row height in pixels. */
+    itemHeight?: number;
+    /** Container height (e.g. "320px" or 320 for px). */
+    height?: string | number;
+    /** Extra rows rendered above/below the visible window. */
+    overscan?: number;
+    /** Per-item template — receives `item` and `index` in loop context. */
+    item?: any;
+    emptyText?: string;
+    children?: Snippet;
+}
+declare const VirtualList: import("svelte").Component<Props, {}, "">;
+type VirtualList = ReturnType<typeof VirtualList>;
+export default VirtualList;

package/dist/widgets/data/calendar-layout.d.ts

@@ -0,0 +1,105 @@
+export declare const MAX_EVENTS = 300;
+export type View = 'month' | 'week';
+export interface CalEvent {
+    key: string;
+    /** The model's object, handed back to on_select untouched. */
+    raw: unknown;
+    /** Plain title; '' when the model gave none. */
+    title: string;
+    start: number;
+    /** Inclusive last day. */
+    end: number;
+    /** 'H:MM' from the string's digits when the start carries a time. */
+    time?: string;
+    minutes: number;
+    color: string;
+}
+export interface Parsed {
+    events: CalEvent[];
+    undated: {
+        key: string;
+        title: string;
+    }[];
+    capped: boolean;
+}
+/** An ISO day (and time) from a string's digits, or undefined. */
+export declare function readDay(v: unknown): {
+    day: number;
+    time?: string;
+    minutes: number;
+} | undefined;
+export declare const dayDate: (day: number) => Date;
+export declare const isoOf: (day: number) => string;
+/** 0 = Sunday. 1970-01-01 was a Thursday. */
+export declare const weekday: (day: number) => number;
+/** The visitor's calendar day for a clock reading. */
+export declare const localDay: (d: Date) => number;
+export declare function monthStart(day: number): number;
+export declare function monthEnd(day: number): number;
+export declare const weekStart: (day: number) => number;
+/** First and last day of the period holding `day`. */
+export declare function period(day: number, view: View): [number, number];
+/** The period `delta` steps from the one starting at `start`. */
+export declare function shiftPeriod(start: number, view: View, delta: number): number;
+/** A safe CSS colour: hex as given, palette names, else the title hash. */
+export declare function eventColor(color: unknown, title: string): string;
+export declare function parseEvents(v: unknown): Parsed;
+/** First day of the period the card opens on (brief 3.1, five rungs). */
+export declare function openPeriod(events: CalEvent[], value: unknown, view: View, today: number): number;
+/** Sundays of the weeks the period touches: 4 to 6 for a month, 1 for a week. */
+export declare function weeksOf(start: number, view: View): number[];
+export interface Segment {
+    ev: CalEvent;
+    col: number;
+    span: number;
+    lane: number;
+    /** The event started before this week (square left end, no edge). */
+    before: boolean;
+    /** The event runs on past this week (square right end). */
+    after: boolean;
+}
+export interface WeekLayout {
+    segments: Segment[];
+    /** Lanes drawn (visible ones only). */
+    lanes: number;
+    /** Hidden events per weekday column. */
+    more: number[];
+    /** Every event touching each day, in lane order (dots, counts). */
+    days: CalEvent[][];
+}
+/** Segments for one week; lanes longest first, then by start. Lanes at or past `cap` are hidden. */
+export declare function layoutWeek(events: CalEvent[], sunday: number, cap?: number): WeekLayout;
+export interface AgendaDay {
+    day: number;
+    events: CalEvent[];
+    /** Spans that started earlier and still cover this day (week view note). */
+    continuing: CalEvent[];
+}
+/**
+ * Events in [from, to] grouped by day in date order. A span lists once, under
+ * its first visible day. `everyDay` keeps days without events (week view).
+ * Within a day: spans and all-day events first, then by time.
+ */
+export declare function agenda(events: CalEvent[], from: number, to: number, everyDay?: boolean): AgendaDay[];
+/** Events touching [from, to]. */
+export declare const countIn: (events: CalEvent[], from: number, to: number) => number;
+/** Where to send a reader from an empty period: the next event after it, else the last one before it. */
+export declare function nearest(events: CalEvent[], from: number, to: number): {
+    dir: 'next' | 'last';
+    ev: CalEvent;
+} | undefined;
+export declare function fmt(locale: string | undefined, opts: Intl.DateTimeFormatOptions): (day: number) => string;
+/**
+ * A day range in the locale's own words via formatRange, so a German card
+ * reads "16.-19. Nov." (with the locale's dash) instead of an English joiner.
+ * The year is added when asked. Runtimes without formatRange get
+ * "May 20 to 22". One day is just that day.
+ */
+export declare function rangeLabel(start: number, end: number, locale?: string, year?: boolean): string;
+/** The card's words in the locale's language; English when the locale is unknown or bad. */
+export declare function words(locale?: string): {
+    today: string;
+    allDay: string;
+    none: string;
+    count: (n: number) => string;
+};

package/dist/widgets/data/calendar-layout.js

@@ -0,0 +1,269 @@
+// widgets/data/calendar-layout.ts: the data side of the `calendar` widget.
+// Pure and DOM-free: it reads model events into clean day ranges, picks the
+// period the card opens on, lists the weeks to draw, cuts events into
+// per-week segments with stable lanes, and groups the agenda. Calendar.svelte
+// only lays out what this returns.
+//
+// Invariants:
+// - Days are integers (days since 1970-01-01, UTC), built from the ISO
+//   string's own digits, so no timezone can move an event to another day.
+// - Nothing here throws. A start that is not an ISO day ("next Tuesday",
+//   "2026-02-31") is kept in `undated`, never dropped silently. Events cap at
+//   MAX_EVENTS.
+// - Colours are a 3- or 6-digit hex or a palette constant; any other model
+//   text falls back to the title hash, so model text never reaches CSS.
+// - Weeks start on Sunday for every locale.
+// - UI words follow the locale: "Today" from Intl, the event count and
+//   "All day" from a small table with an English fallback.
+import { plain } from '../data-kit/format.js';
+import { colorOf } from '../composite/week-schedule.js';
+import { uniqueKeys } from '../../utils/safe-props.js';
+export const MAX_EVENTS = 300;
+const DAY_MS = 86_400_000;
+// ── Days ────────────────────────────────────────────────────────────────────
+const ISO = /^\s*(\d{4})-(\d{2})-(\d{2})(?:$|[T ](\d{2}):(\d{2}))?/;
+/** An ISO day (and time) from a string's digits, or undefined. */
+export function readDay(v) {
+    if (typeof v !== 'string')
+        return undefined;
+    const m = ISO.exec(v);
+    if (!m)
+        return undefined;
+    const [y, mo, d] = [+m[1], +m[2] - 1, +m[3]];
+    const t = Date.UTC(y, mo, d);
+    const back = new Date(t);
+    // Date.UTC rolls 2026-02-31 over to March 3; the round trip catches it.
+    if (back.getUTCFullYear() !== y || back.getUTCMonth() !== mo || back.getUTCDate() !== d)
+        return undefined;
+    const h = m[4] === undefined ? undefined : +m[4];
+    const min = m[5] === undefined ? 0 : +m[5];
+    const timed = h !== undefined && h < 24 && min < 60;
+    return { day: t / DAY_MS, time: timed ? `${h}:${m[5]}` : undefined, minutes: timed ? h * 60 + min : -1 };
+}
+export const dayDate = (day) => new Date(day * DAY_MS);
+export const isoOf = (day) => dayDate(day).toISOString().slice(0, 10);
+/** 0 = Sunday. 1970-01-01 was a Thursday. */
+export const weekday = (day) => (((day + 4) % 7) + 7) % 7;
+/** The visitor's calendar day for a clock reading. */
+export const localDay = (d) => Date.UTC(d.getFullYear(), d.getMonth(), d.getDate()) / DAY_MS;
+export function monthStart(day) {
+    const d = dayDate(day);
+    return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1) / DAY_MS;
+}
+export function monthEnd(day) {
+    const d = dayDate(day);
+    return Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 0) / DAY_MS;
+}
+export const weekStart = (day) => day - weekday(day);
+/** First and last day of the period holding `day`. */
+export function period(day, view) {
+    return view === 'week' ? [weekStart(day), weekStart(day) + 6] : [monthStart(day), monthEnd(day)];
+}
+/** The period `delta` steps from the one starting at `start`. */
+export function shiftPeriod(start, view, delta) {
+    if (view === 'week')
+        return start + 7 * delta;
+    const d = dayDate(start);
+    return Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + delta, 1) / DAY_MS;
+}
+const overlaps = (e, from, to) => e.start <= to && e.end >= from;
+// ── Events ──────────────────────────────────────────────────────────────────
+/** A safe CSS colour: hex as given, palette names, else the title hash. */
+export function eventColor(color, title) {
+    if (typeof color === 'string' && /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.test(color.trim()))
+        return color.trim().toLowerCase();
+    return colorOf(color, title);
+}
+export function parseEvents(v) {
+    const all = Array.isArray(v) ? v : [];
+    const items = all.slice(0, MAX_EVENTS).map((x) => (x !== null && typeof x === 'object' ? x : {}));
+    const keys = uniqueKeys(items, (r, i) => (r.id === undefined || r.id === null ? `i${i}` : r.id));
+    const events = [];
+    const undated = [];
+    items.forEach((r, i) => {
+        const title = plain(r.title).slice(0, 200);
+        const s = readDay(r.start);
+        if (!s) {
+            undated.push({ key: keys[i], title });
+            return;
+        }
+        const e = readDay(r.end);
+        let [start, end] = [s.day, e ? e.day : s.day];
+        if (end < start)
+            [start, end] = [end, start];
+        events.push({ key: keys[i], raw: all[i], title, start, end, time: s.time, minutes: s.minutes, color: eventColor(r.color, title) });
+    });
+    return { events, undated, capped: all.length > MAX_EVENTS };
+}
+// ── Which period opens ──────────────────────────────────────────────────────
+/** First day of the period the card opens on (brief 3.1, five rungs). */
+export function openPeriod(events, value, view, today) {
+    const at = (day) => period(day, view)[0];
+    const v = readDay(value);
+    if (v)
+        return at(v.day);
+    if (!events.length)
+        return at(today);
+    const [from, to] = period(today, view);
+    if (events.some((e) => overlaps(e, from, to)))
+        return at(today);
+    const ahead = events.filter((e) => e.start >= today);
+    if (ahead.length)
+        return at(Math.min(...ahead.map((e) => e.start)));
+    return at(Math.max(...events.map((e) => e.start)));
+}
+/** Sundays of the weeks the period touches: 4 to 6 for a month, 1 for a week. */
+export function weeksOf(start, view) {
+    if (view === 'week')
+        return [weekStart(start)];
+    const first = weekStart(monthStart(start));
+    const last = monthEnd(start);
+    const out = [];
+    for (let w = first; w <= last; w += 7)
+        out.push(w);
+    return out;
+}
+const byDayOrder = (a, b) => a.start - b.start || b.end - b.start - (a.end - a.start) || a.minutes - b.minutes;
+/** Segments for one week; lanes longest first, then by start. Lanes at or past `cap` are hidden. */
+export function layoutWeek(events, sunday, cap = Infinity) {
+    const sat = sunday + 6;
+    const segs = events
+        .filter((e) => overlaps(e, sunday, sat))
+        .map((ev) => {
+        const s = Math.max(ev.start, sunday);
+        const e = Math.min(ev.end, sat);
+        return { ev, col: s - sunday, span: e - s + 1, lane: 0, before: ev.start < sunday, after: ev.end > sat };
+    })
+        .sort((a, b) => b.span - a.span || a.col - b.col || a.ev.minutes - b.ev.minutes);
+    // Each lane is a row of 7 taken flags; a segment takes the first lane free across its days.
+    const taken = [];
+    for (const s of segs) {
+        const cols = Array.from({ length: s.span }, (_, i) => s.col + i);
+        let lane = taken.findIndex((row) => cols.every((c) => !row[c]));
+        if (lane < 0)
+            lane = taken.push(Array(7).fill(false)) - 1;
+        for (const c of cols)
+            taken[lane][c] = true;
+        s.lane = lane;
+    }
+    const more = [0, 0, 0, 0, 0, 0, 0];
+    const days = [[], [], [], [], [], [], []];
+    const ordered = [...segs].sort((a, b) => a.lane - b.lane);
+    for (const s of ordered) {
+        for (let c = s.col; c < s.col + s.span; c++) {
+            days[c].push(s.ev);
+            if (s.lane >= cap)
+                more[c]++;
+        }
+    }
+    const shown = segs.filter((s) => s.lane < cap);
+    return { segments: shown, lanes: Math.min(taken.length, cap), more, days };
+}
+/**
+ * Events in [from, to] grouped by day in date order. A span lists once, under
+ * its first visible day. `everyDay` keeps days without events (week view).
+ * Within a day: spans and all-day events first, then by time.
+ */
+export function agenda(events, from, to, everyDay = false) {
+    const groups = new Map();
+    if (everyDay)
+        for (let d = from; d <= to; d++)
+            groups.set(d, { day: d, events: [], continuing: [] });
+    const inside = events.filter((e) => overlaps(e, from, to)).sort(byDayOrder);
+    for (const e of inside) {
+        const d = Math.max(e.start, from);
+        if (!groups.has(d))
+            groups.set(d, { day: d, events: [], continuing: [] });
+        groups.get(d).events.push(e);
+        if (everyDay)
+            for (let c = d + 1; c <= Math.min(e.end, to); c++)
+                groups.get(c).continuing.push(e);
+    }
+    const out = [...groups.values()].sort((a, b) => a.day - b.day);
+    for (const g of out)
+        g.events.sort((a, b) => Number(a.minutes >= 0) - Number(b.minutes >= 0) || a.minutes - b.minutes);
+    return out;
+}
+/** Events touching [from, to]. */
+export const countIn = (events, from, to) => events.filter((e) => overlaps(e, from, to)).length;
+/** Where to send a reader from an empty period: the next event after it, else the last one before it. */
+export function nearest(events, from, to) {
+    const after = events.filter((e) => e.start > to).sort((a, b) => a.start - b.start)[0];
+    if (after)
+        return { dir: 'next', ev: after };
+    const before = events.filter((e) => e.end < from).sort((a, b) => b.start - a.start)[0];
+    return before ? { dir: 'last', ev: before } : undefined;
+}
+// ── Formatting ──────────────────────────────────────────────────────────────
+/** An Intl formatter in UTC days; a bad locale falls back to the runtime default. */
+function formatter(locale, opts) {
+    try {
+        return new Intl.DateTimeFormat(locale, { ...opts, timeZone: 'UTC' });
+    }
+    catch {
+        return new Intl.DateTimeFormat(undefined, { ...opts, timeZone: 'UTC' });
+    }
+}
+export function fmt(locale, opts) {
+    const f = formatter(locale, opts);
+    return (day) => f.format(dayDate(day));
+}
+/**
+ * A day range in the locale's own words via formatRange, so a German card
+ * reads "16.-19. Nov." (with the locale's dash) instead of an English joiner.
+ * The year is added when asked. Runtimes without formatRange get
+ * "May 20 to 22". One day is just that day.
+ */
+export function rangeLabel(start, end, locale, year = false) {
+    const opts = { month: 'short', day: 'numeric', ...(year ? { year: 'numeric' } : {}) };
+    const f = formatter(locale, opts);
+    if (start === end)
+        return f.format(dayDate(start));
+    try {
+        return f.formatRange(dayDate(start), dayDate(end));
+    }
+    catch {
+        const md = fmt(locale, { month: 'short', day: 'numeric' });
+        const sameMonth = monthStart(start) === monthStart(end);
+        const out = `${md(start)} to ${sameMonth ? fmt(locale, { day: 'numeric' })(end) : md(end)}`;
+        return year ? `${out}, ${fmt(locale, { year: 'numeric' })(end)}` : out;
+    }
+}
+const EN = { one: 'event', other: 'events', none: 'No events', allDay: 'All day' };
+// ponytail: a handful of languages; add a row when a card needs another.
+const WORDS = {
+    en: EN,
+    de: { one: 'Termin', other: 'Termine', none: 'Keine Termine', allDay: 'Ganztägig' },
+    fr: { one: 'événement', other: 'événements', none: 'Aucun événement', allDay: 'Toute la journée' },
+    es: { one: 'evento', other: 'eventos', none: 'Sin eventos', allDay: 'Todo el día' },
+    it: { one: 'evento', other: 'eventi', none: 'Nessun evento', allDay: 'Tutto il giorno' },
+    pt: { one: 'evento', other: 'eventos', none: 'Sem eventos', allDay: 'Dia inteiro' },
+    nl: { one: 'afspraak', other: 'afspraken', none: 'Geen afspraken', allDay: 'Hele dag' }
+};
+/** The card's words in the locale's language; English when the locale is unknown or bad. */
+export function words(locale) {
+    let lang = 'en';
+    let today = 'Today';
+    let plural = (n) => (n === 1 ? 'one' : 'other');
+    try {
+        const rt = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });
+        lang = rt.resolvedOptions().locale.split('-')[0];
+        const t = rt.format(0, 'day');
+        today = t.charAt(0).toLocaleUpperCase(locale) + t.slice(1);
+        const pr = new Intl.PluralRules(locale);
+        plural = (n) => pr.select(n);
+    }
+    catch {
+        /* bad locale: English */
+    }
+    const w = WORDS[lang];
+    if (!w)
+        today = 'Today';
+    const W = w ?? EN;
+    return {
+        today,
+        allDay: W.allDay,
+        none: W.none,
+        count: (n) => `${n} ${plural(n) === 'one' ? W.one : W.other}`
+    };
+}

package/dist/widgets/data/chart-layout.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Categorical palette in draw order. Brand blue first, then hues that read as
+ * categories. Status colours (red, green) are not in it and amber sits late, so
+ * a second series (a target, a comparison) never reads as an error or a win.
+ * A spec that wants status colours passes them in `colors`.
+ */
+export declare const CATEGORICAL: string[];
+/** The i-th series colour: the spec's `colors[i]`, else the palette in order. */
+export declare function seriesColor(i: number, colors: readonly string[]): string;
+/**
+ * Colours for the points of ONE series (bar, line, heatmap, gauge, radar).
+ * One series is one colour. Points differ only when the spec says so: a point's
+ * own `color`, or a `colors` list longer than one (read as per point).
+ */
+export declare function pointColors(data: readonly object[], colors: readonly string[]): string[];
+/** Slice colours for pie and donut: every slice is its own category. */
+export declare function sliceColors(data: readonly object[], colors: readonly string[]): string[];
+export interface AxisLabelFit {
+    /** echarts `axisLabel.interval`: 0 shows all, a function picks which. */
+    interval: number | ((index: number) => boolean);
+    rotate: number;
+    /** Set when labels are long enough to shorten once rotated. */
+    formatter?: (value: string) => string;
+}
+/**
+ * How a category axis shows `labels` across `plotWidth` px. In order of
+ * preference: every label flat, every label rotated (30 then 45 degrees),
+ * then rotated and thinned to evenly spaced labels that always keep the first
+ * and the last. Never echarts' silent auto-drop. `null` when the width is not
+ * known yet (echarts' own default applies until the first measure). `measure`
+ * is the label's rendered width in px; the default estimates from its length.
+ */
+export declare function fitAxisLabels(labels: readonly string[], plotWidth: number, fontSize?: number, measure?: (text: string) => number): AxisLabelFit | null;
+/**
+ * Legend line per slice: "Label  value · pct%". Values share the data's own
+ * precision (4.8, 5.1, 3 print as 4.8, 5.1, 3.0) so the column reads evenly.
+ */
+export declare function sliceLegendText(points: readonly {
+    label: string;
+    value?: number;
+}[]): Map<string, string>;
+export interface PieLayout {
+    center: [string, string];
+    radius: number;
+    legend: 'right' | 'bottom';
+    /** px the chart grows by to hold a legend below the pie. */
+    extraHeight: number;
+    /** Legend text width cap (px) when a line is wider than the chart: it wraps. */
+    textWidth?: number;
+}
+/**
+ * Where the pie and its legend go in a `width` x `height` box. The legend sits
+ * to the right while the pie keeps a useful size beside it; otherwise (phone
+ * width) it moves below and the chart grows by the legend's height, so the pie
+ * keeps its size and no legend line is cut.
+ */
+export declare function pieLayout(width: number, height: number, legendTexts: readonly string[], fontSize?: number): PieLayout;