@kitlangton/knobs 0.0.0-stage → 0.2.0

package/dist/types/panel/swipe.d.ts

@@ -0,0 +1,114 @@
+/** A pause this long (ms) with no wheel events ends a gesture. */
+export declare const GESTURE_GAP = 120;
+export interface WheelSample {
+    readonly deltaX: number;
+    readonly deltaY: number;
+    readonly deltaMode: number;
+    readonly shiftKey: boolean;
+    /** ms */
+    readonly timeStamp: number;
+    /** Safari only: false when natural scrolling is off, so the deltas follow the fingers. */
+    readonly webkitDirectionInvertedFromDevice?: boolean;
+    /**
+     * Chromium 151+ (Chrome, Edge, Brave): true for the inertia the OS sends after the fingers lift
+     * (the platform's own momentum phase). Where it exists the pan needs no guessing; where it
+     * doesn't (Safari, Firefox), the lift is recognised from the stream's shape.
+     */
+    readonly momentum?: boolean;
+}
+export interface PanHandlers {
+    /** Asked at the start of each gesture or notch; false leaves it to the page. */
+    accept?(): boolean;
+    /** Finger travel (px) since the last call: positive rightwards and downwards. */
+    move(dx: number, dy: number): void;
+    /**
+     * The fingers seem to have lifted: a cue to let go visually. It comes as soon as a lift is
+     * suspected, before `end` (which waits for proof); a move after it means they hadn't.
+     */
+    lift?(): void;
+    /** After one or more moves: the fingers lifted (their momentum is ignored) or went still. */
+    end(): void;
+    /** A mouse wheel notch (or ⇧ + wheel): one step, rightwards or down being +1. */
+    step?(direction: -1 | 1): void;
+}
+/**
+ * Turns wheel events into direct manipulation. A horizontal two-finger pan moves 1:1 with the
+ * fingers from its first event; when they lift, the momentum macOS keeps sending is recognised
+ * and ignored, so things stop where the fingers stopped. Vertical gestures are never claimed.
+ *
+ * A lift is spotted the moment it happens, by its pause and spike, or by a steady fade when a
+ * stream has no pause. Suspect events are held back rather than applied: a finger event in their
+ * place releases them, and so does one breaking the coast with no pause (a new touch always
+ * pauses), so a false alarm costs a few ms, never distance. A push stronger than the momentum it
+ * interrupts starts a new gesture at once.
+ *
+ * `feed` returns whether the event belongs to a claimed gesture, in which case the caller should
+ * `preventDefault()` it (so the browser doesn't scroll or swipe back a page). `idle` ends the
+ * gesture once the wheel has been quiet for `GESTURE_GAP`.
+ */
+export declare function createPan(handlers: PanHandlers, options?: {
+    axes?: "x" | "xy";
+}): {
+    feed: (event: WheelSample) => boolean;
+    /** The wheel went quiet: whatever was in hand is over. */
+    idle(): void;
+};
+/** Feeds `el`'s wheel events to a pan (see `createPan`), ending gestures after a quiet spell. */
+export declare function onPan(el: HTMLElement, handlers: PanHandlers, options?: {
+    axes?: "x" | "xy";
+}): {
+    feed: (event: WheelSample) => boolean;
+    /** The wheel went quiet: whatever was in hand is over. */
+    idle(): void;
+};
+/** An option's box in its container (px): where the selection pill sits on it. */
+export interface Slot {
+    readonly left: number;
+    readonly right: number;
+    readonly top: number;
+}
+/** A pill mid-pan: the option it belongs to, and how far (px) the fingers have pushed it off. */
+export interface Slide {
+    readonly index: number;
+    readonly offset: number;
+}
+/** Whether a pill's offset is past an end: its give (see give.ts). */
+export declare const giving: (slots: readonly Slot[], { index, offset }: Slide) => boolean;
+/**
+ * Pushes the pill `delta` px; it joins a neighbour once past halfway to it. Past an end it gives
+ * like every control does (see give.ts): a little, less and less, and turning back takes the give
+ * up 1:1 before it moves on.
+ */
+export declare function slide(slots: readonly Slot[], from: Slide, delta: number): Slide;
+/**
+ * The pill's live edges: its centre is its option's plus the offset, and its width blends toward
+ * the neighbour it heads for, so it's continuous as the selection changes hands. Past the ends the
+ * offset is its give.
+ */
+export declare function pillAt(slots: readonly Slot[], { index, offset }: Slide): Slot;
+/** The selection pill's edges while a pan holds it (px in `box`), so the GPU can draw it there. */
+export declare const livePill: (box: Element) => Slot | undefined;
+/**
+ * Pans a row of options: the selection pill follows the fingers, the selection changes to
+ * whichever option the pill passes halfway to (so one pan can cross several), and when the
+ * gesture ends the pill springs back into its option's slot. A notch steps one option.
+ */
+export declare function panOptions(el: HTMLElement, o: {
+    /** The pill's positioning box. */
+    readonly box: HTMLElement;
+    readonly pill: HTMLElement;
+    buttons(): readonly HTMLElement[];
+    /** The selected option's index, or -1. */
+    selected(): number;
+    /** `coalesce`: a later change in the same gesture, folded into its undo step. */
+    select(index: number, coalesce: boolean): void;
+    /** Puts the pill back on the selected option, with its transition. */
+    rest(): void;
+    wake?(): void;
+    /** The pill's narrowest width (px). */
+    readonly minWidth?: number;
+    /** Places the pill's top too, for options that wrap onto rows. */
+    readonly rows?: boolean;
+    /** A row held in its active state (`knobs-active`) while the pill is in hand. */
+    readonly row?: HTMLElement;
+}): void;

package/dist/types/panel/switcher.d.ts

@@ -0,0 +1,20 @@
+import type { ChoiceKey } from "../core/adapter.js";
+import { type Schema, type Values } from "../core/schema.js";
+import type { Controls } from "../core/store.js";
+export type { ChoiceKey };
+export interface SwitcherOptions<S extends Schema> {
+    readonly field?: ChoiceKey<S>;
+    readonly label?: string;
+    readonly onUpdate?: (activeName: string) => void;
+}
+export declare function getSwitcherOptions<S extends Schema>(controls: Controls<S>, field?: ChoiceKey<S>): {
+    options: {
+        id: string;
+        name: string;
+        values?: Values<S>;
+        choose(): void;
+    }[];
+    index: number;
+    activeName: string;
+};
+export declare function attachVariantSwitcher<S extends Schema>(element: HTMLElement, controls: Controls<S>, switcherOptions?: SwitcherOptions<S>): () => void;

package/dist/types/panel/tabs.d.ts

@@ -0,0 +1,31 @@
+import { Edges } from "./motion.js";
+export interface TabSpec {
+    readonly id: string;
+    readonly label: string;
+}
+/**
+ * A panel's tab strip: text tabs over a hairline, the chosen one marked by an underline that
+ * slides to it (its leading edge first, the trailing one following, as the selection pills do).
+ * The strip is one ↑↓ stop; ←/→ on it switch tabs.
+ */
+export interface TabStrip {
+    readonly element: HTMLElement;
+    readonly bar: HTMLElement;
+    /** The underline's edges for the GPU overlay (px from the strip's left). */
+    readonly edges: Edges;
+    buttons: HTMLButtonElement[];
+    readonly tabs: readonly TabSpec[];
+    readonly active: string | undefined;
+    /** Swaps in another set of tabs, keeping the strip. */
+    set(tabs: readonly TabSpec[], active: string | undefined): void;
+    /** Marks `id` chosen and slides the underline to it (or places it, when `animate` is false). */
+    select(id: string, animate?: boolean): void;
+    /**
+     * A small count after a tab's label ("" takes it away); `label` is what it means, for
+     * assistive tech and the tooltip.
+     */
+    count(id: string, text: string, label?: string): void;
+    focus(options?: FocusOptions): void;
+    dispose(): void;
+}
+export declare function createTabStrip(doc: Document, choose: (id: string) => void): TabStrip;

package/dist/types/panel/thumb.d.ts

@@ -0,0 +1,36 @@
+import { type Band } from "./give.js";
+/** A switch's geometry (px): the thumb's free travel at rest, its size, its inset, and how much wider a press makes it. */
+export interface SwitchBox {
+    readonly travel: number;
+    readonly size: number;
+    readonly pad: number;
+    readonly press: number;
+}
+/** How far a held thumb's leading edge stretches past an end (px): a switch is small. */
+export declare const SWITCH_GIVE = 3;
+/** A lift faster than this (px/ms) is a flick: it decides by its direction. */
+export declare const FLICK = 0.2;
+/** Where a pressed thumb sits for a value (px from its leftmost spot); mixed waits in the middle. */
+export declare const heldAt: (box: SwitchBox, on: boolean | "mixed") => number;
+/** Whether a thumb at `at` reads as on: past the middle. */
+export declare const onAt: (box: SwitchBox, at: number) => boolean;
+/** Moves a held thumb `d` px, giving at the ends. */
+export declare const pushThumb: (box: SwitchBox, from: Band, d: number) => Band;
+/** Finger travel (px) over which a held thumb widens to its pressed size, so it never jumps. */
+export declare const PRESS_IN = 6;
+/**
+ * A held thumb's edges (px from the switch's left): pressed wide by `pressed` (0…1) of its press,
+ * toward the side it can go (so unpressed it's exactly the resting thumb), its leading edge
+ * giving past an end.
+ */
+export declare function thumbEdges(box: SwitchBox, { at, give }: Band, pressed?: number): [number, number];
+/** How a pan lets go: a flick goes its way, anything slower stays on the side the thumb is on. */
+export declare const settleOn: (box: SwitchBox, at: number, speed: number) => boolean;
+/** A held thumb's edges (px from the switch's left), so the GPU can draw it there too. */
+export declare const liveThumb: (toggle: Element) => readonly [number, number] | undefined;
+/** Pans `toggle`'s thumb from anywhere on `row`; `set` changes the value (`coalesce`: a later change in one gesture). */
+export declare function panSwitch(row: HTMLElement, toggle: HTMLElement, o: {
+    value(): boolean | "mixed";
+    set(on: boolean, coalesce: boolean): void;
+    wake(): void;
+}): void;

package/dist/types/panel/toolbar-grid.d.ts

@@ -0,0 +1,6 @@
+/**
+ * How many equal columns a toolbar's buttons take in `avail` px: as many as fit at the widest
+ * button's width, then balanced so the rows hold counts as even as they can (four buttons wrap as
+ * two and two, never three and one; five as three and two).
+ */
+export declare function toolbarColumns(count: number, widest: number, avail: number, gap: number): number;

package/dist/types/react/Knobs.d.ts

@@ -0,0 +1,15 @@
+import { type ReactElement, type Ref } from "react";
+import { type KnobsPanelProps } from "../core/adapter.js";
+import type { Schema } from "../core/schema.js";
+import type { Controls } from "../core/store.js";
+export type { KnobsPanelProps };
+export declare function useKnobs<S extends Schema, E extends HTMLElement = HTMLElement>(controls: Controls<S>): (element: E | null) => void;
+export declare function Knobs<S extends Schema>({ controls, children, }: {
+    controls: Controls<S>;
+    children: ReactElement<{
+        ref?: Ref<HTMLElement>;
+    }>;
+}): ReactElement<{
+    ref?: Ref<HTMLElement>;
+}, string | import("react").JSXElementConstructor<any>>;
+export declare function KnobsPanel<S extends Schema>(props: KnobsPanelProps<S>): import("react").JSX.Element | null;

package/dist/types/react/VariantSwitcher.d.ts

@@ -0,0 +1,10 @@
+import { type ReactNode } from "react";
+import type { ChoiceKey } from "../core/adapter.js";
+import type { Schema } from "../core/schema.js";
+import type { Controls } from "../core/store.js";
+export declare function VariantSwitcher<S extends Schema>({ controls, field, children, label, }: {
+    controls: Controls<S>;
+    field?: ChoiceKey<S>;
+    children?: ReactNode;
+    label?: string;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,3 @@
+export { useControls, useModified, useValue } from "./useControls.js";
+export { Knobs, KnobsPanel, useKnobs, type KnobsPanelProps } from "./Knobs.js";
+export { VariantSwitcher } from "./VariantSwitcher.js";

package/dist/types/react/useControls.d.ts

@@ -0,0 +1,11 @@
+import type { Schema, Values } from "../core/schema.js";
+import type { Controls } from "../core/store.js";
+export declare function useControls<S extends Schema>(controls: Controls<S>): Values<S>;
+/**
+ * One key's value, re-rendering the component only when that key changes.
+ */
+export declare function useValue<S extends Schema, K extends keyof Values<S> & string>(controls: Controls<S>, key: K): Values<S>[K];
+/**
+ * Whether a key (or, without one, anything) differs from its default: a "modified" dot beside a heading.
+ */
+export declare function useModified<S extends Schema>(controls: Controls<S>, key?: keyof S & string): boolean;

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

@@ -0,0 +1,50 @@
+import { type Accessor, type JSX } from "solid-js";
+import { type ChoiceKey, type KnobsPanelProps } from "../core/adapter.js";
+import { type Schema, type Values } from "../core/schema.js";
+import type { Controls } from "../core/store.js";
+export type { KnobsPanelProps };
+/**
+ * Reactive Solid accessor for a controls store.
+ * Returns `controls.getServerSnapshot()` (`locked`) during SSR, and updates reactively on the client.
+ */
+export declare function useControls<S extends Schema>(controls: Controls<S>): Accessor<Values<S>>;
+/**
+ * One key's value as an accessor that changes only when that key does, so a component reading
+ * it re-runs for its own row and no other.
+ */
+export declare function useValue<S extends Schema, K extends keyof Values<S> & string>(controls: Controls<S>, key: K): Accessor<Values<S>[K]>;
+/**
+ * Whether a key (or, without one, anything) differs from its default, as an accessor that
+ * changes only when the answer does: a "modified" dot beside a heading.
+ */
+export declare function useModified<S extends Schema>(controls: Controls<S>, key?: keyof S & string): Accessor<boolean>;
+/**
+ * Solid ref callback (`ref={useKnobs(controls)}`) that attaches the floating tuning chip and panel.
+ */
+export declare function useKnobs<S extends Schema, E extends HTMLElement = HTMLElement>(controls: Controls<S>): (element: E) => void;
+/**
+ * Solid `use:knobs={controls}` directive for attaching controls to an element.
+ */
+export declare function knobs<S extends Schema>(element: HTMLElement, accessor: Accessor<Controls<S>>): void;
+/**
+ * Attaches `props.controls` directly to its single HTML child element without adding wrapper DOM.
+ */
+export declare function Knobs<S extends Schema>(props: {
+    controls: Controls<S>;
+    children: JSX.Element;
+}): JSX.Element;
+/**
+ * Mounts an inline `knobs` panel inside a Solid component tree. The panel mounts once per
+ * `controls`; `descriptors` and `values` flow into it as updates, so a change touches only the rows
+ * it changes and the panel never re-renders as a whole.
+ */
+export declare function KnobsPanel<S extends Schema>(props: KnobsPanelProps<S>): JSX.Element;
+/**
+ * In-place keyboard (`1–9`, `←/→`) and hover switcher for a choice field or presets/variants in Solid.
+ */
+export declare function VariantSwitcher<S extends Schema>(props: {
+    controls: Controls<S>;
+    field?: ChoiceKey<S>;
+    label?: string;
+    children?: JSX.Element;
+}): JSX.Element;

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

@@ -0,0 +1 @@
+export { labPreset, presetCss, problemsPreset, type TokenPreset } from "../core/theme.js";

package/dist/types/ui/activity-css.d.ts

@@ -0,0 +1 @@
+export declare const activityCss: string;

package/dist/types/ui/activity-model.d.ts

@@ -0,0 +1,122 @@
+/** The built-in kinds, each with its icon and tint. */
+export type ActivityKind = "you" | "agent" | "proposal" | "review" | "pr" | "build" | "blocked" | "shipped";
+export interface ActivityEvent {
+    /** Unique, and the same across `set()`: rows keep their identity and glide. */
+    readonly id: string;
+    /** A built-in kind (its icon and tint), or a name of your own with `icon` and `tint`. */
+    readonly kind?: ActivityKind | (string & {});
+    /** Who: "You", "Agent", "Ryan". */
+    readonly actor?: string;
+    /** One line; it fades at its end when cut off. A group without one says "3 updates". */
+    readonly title?: string;
+    /** Trailing, already formatted ("2m", "9:41"); it rolls when it changes. */
+    readonly time?: string;
+    /** A duration chip, "▶ 0:32": seconds, or text as it should read. */
+    readonly duration?: number | string;
+    /** Small thumbnails before the time (image URLs; four at most show). */
+    readonly thumbs?: readonly string[];
+    /** SVG markup, a glyph or a node in place of the kind's icon. */
+    readonly icon?: string | Node;
+    /** A CSS colour in place of the kind's tint. */
+    readonly tint?: string;
+    /** Makes a group that opens in place ("Agent · 3 updates"). One level deep. */
+    readonly children?: readonly ActivityEvent[];
+    /** The live or latest step: its node takes a ring. */
+    readonly current?: boolean;
+    /** Quieter: past steps, minor updates. */
+    readonly dimmed?: boolean;
+}
+export interface ActivityRow {
+    readonly id: string;
+    readonly event: ActivityEvent;
+    /** 0 for an event, 1 for one inside an open group. */
+    readonly depth: 0 | 1;
+    readonly parent: string | null;
+    /** Has children: it opens and closes. */
+    readonly group: boolean;
+    readonly expanded: boolean;
+}
+/** The rows on show: every event, and the children of open groups right after their group. */
+export declare function flattenActivity(events: readonly ActivityEvent[], expanded: ReadonlySet<string>): ActivityRow[];
+/** Every event by id, children included, with its group. */
+export declare function indexActivity(events: readonly ActivityEvent[]): Map<string, {
+    event: ActivityEvent;
+    parent: string | null;
+}>;
+export type ActivityKey = "ArrowUp" | "ArrowDown" | "ArrowLeft" | "ArrowRight" | "Home" | "End";
+export declare const isActivityKey: (key: string) => key is ActivityKey;
+/**
+ * What a key does from the selected row: ↑/↓ move (from nothing, to the first or the last),
+ * Home/End go to the ends, → opens a closed group and steps into an open one, ← closes an open
+ * group and steps out of a child to its group.
+ */
+export declare function navigateActivity(rows: readonly ActivityRow[], selected: string | null, key: ActivityKey): {
+    select?: string;
+    toggle?: {
+        id: string;
+        expanded: boolean;
+    };
+};
+/**
+ * Whether the rail takes a key it navigated: ↑/↓ and Home/End whenever there are rows (at an end
+ * they hold the selection), ← and → only when they open, close or step. A ← or → that does
+ * nothing is left to the page (a review stage stepping frames, say).
+ */
+export declare function takesActivityKey(key: ActivityKey, result: {
+    select?: string;
+    toggle?: unknown;
+}, rows: number): boolean;
+/**
+ * Where the selection goes when its row leaves the rows on show: to its group when that closed
+ * over it, else nowhere.
+ */
+export declare function keepSelection(rows: readonly ActivityRow[], selected: string | null, parentOf: (id: string) => string | null | undefined): string | null;
+/** What last moved the selection: keys show it as a tint, a pointer hides it. */
+export type ActivityInput = "key" | "pointer" | "blur" | "code";
+/**
+ * Whether the selection's tint shows: keys turn it on, a pointer turns it off (a click selects
+ * with no ring), losing focus turns it off unless the page's keys drive it, and a host's
+ * `select()` leaves it as it was.
+ */
+export declare function showsSelection(showing: boolean, input: ActivityInput, keys?: "focus" | "page"): boolean;
+/** Which ids came, went and stayed between two orders of rows. */
+export declare function diffActivity(before: readonly string[], after: readonly string[]): {
+    entered: string[];
+    left: string[];
+    kept: string[];
+};
+/** Rows stacked top to bottom from `top`: each one's y, and the bottom of the last. */
+export declare function stackRows(heights: readonly number[], top?: number, gap?: number): {
+    y: number[];
+    bottom: number;
+};
+export interface RailNode {
+    /** The node's centre. */
+    readonly y: number;
+    /** How far the line keeps clear of it on each side. */
+    readonly r: number;
+}
+/**
+ * The line through the nodes, as segments between neighbours that stop clear of each node, and
+ * only within `[from, to]` (the line's ends, which glide as rows come and go). One continuous
+ * thread at rest: nothing past the last node, nothing before the first.
+ */
+export declare function railSegments(nodes: readonly RailNode[], from: number, to: number): [number, number][];
+/**
+ * The scroll while a change takes the content from height `h0` to `h1` (now at `height`): it goes
+ * from `from` to where it has to end (no further down than the shorter content allows) in step
+ * with the height, and the space stays tall enough for it meanwhile. Closing a group at the
+ * scroll's end, the rows above glide down with the drawer instead of dropping in a frame.
+ */
+export declare function holdScroll(hold: {
+    readonly from: number;
+    readonly h0: number;
+    readonly h1: number;
+}, height: number, view: number): {
+    scroll: number;
+    space: number;
+};
+/** "0:32", "4:05", "1:02:03"; text passes through as it is. */
+export declare function formatDuration(duration: number | string): string;
+/** A group's title when it has none of its own: "1 update", "3 updates". */
+export declare function groupTitle(count: number): string;

package/dist/types/ui/activity.d.ts

@@ -0,0 +1,67 @@
+import { type ActivityEvent } from "./activity-model.js";
+import { type UiLook } from "./look.js";
+export interface ActivityOptions extends UiLook {
+    readonly events: readonly ActivityEvent[];
+    /** The selected event's id. */
+    readonly selected?: string | null;
+    /** Groups open from the start. */
+    readonly expanded?: Iterable<string>;
+    /** Keys and clicks moved the selection (a host's `select()` doesn't call it). */
+    readonly onSelect?: (id: string, event: ActivityEvent, source: "key" | "pointer") => void;
+    /** Enter on the selected row (on a group with no `onActivate`, Enter opens or closes it). */
+    readonly onActivate?: (id: string, event: ActivityEvent) => void;
+    readonly onToggle?: (id: string, expanded: boolean) => void;
+    /** Makes the duration chip a button. */
+    readonly onPlay?: (id: string, event: ActivityEvent) => void;
+    /**
+     * Where the newest events are: `"bottom"` (the default; oldest first) or `"top"`. `add()` puts
+     * an event there, and new events slide in from that side.
+     */
+    readonly newest?: "top" | "bottom";
+    /** Stay pinned to the newest end when it was in view as events arrive (default true). */
+    readonly follow?: boolean;
+    /**
+     * Where the keys come from: `"focus"` (the default) while the rail has focus, or `"page"` from
+     * anywhere a focused field or widget doesn't take them.
+     */
+    readonly keys?: "focus" | "page";
+    /** Icons (SVG markup or a glyph) for your own kinds, or in place of built-in ones. */
+    readonly icons?: Readonly<Record<string, string>>;
+    /** Tints (CSS colours) for your own kinds, or in place of built-in ones. */
+    readonly tints?: Readonly<Record<string, string>>;
+    /** The rail's accessible name. */
+    readonly label?: string;
+    /** Shown with no events. */
+    readonly empty?: string;
+}
+export interface Activity {
+    readonly element: HTMLElement;
+    /** New events: those that stay glide to their places, new ones bloom in, gone ones soften out. */
+    set(events: readonly ActivityEvent[]): void;
+    /** One more event at the newest end. */
+    add(event: ActivityEvent): void;
+    /**
+     * New events and where the newest are, in one change: rows glide to their new places, as with
+     * `set` (flipping `newest` with the events reversed reverses the rail in place).
+     */
+    update(next: {
+        events?: readonly ActivityEvent[];
+        newest?: "top" | "bottom";
+    }): void;
+    /** Selects (opening its group); `null` clears. Doesn't call `onSelect`. */
+    select(id: string | null): void;
+    readonly selected: string | null;
+    expand(id: string, expanded?: boolean): void;
+    isExpanded(id: string): boolean;
+    focus(): void;
+    destroy(): void;
+    /** The same as `destroy`, as the other pieces name it. */
+    dispose(): void;
+}
+/**
+ * A vertical rail of events: who did what, one line each, with a kind's icon on one continuous
+ * line. Groups open in place with their children on the same line. ↑/↓, Home/End move the
+ * selection (a tint that shows only once keys move it), ←/→ close and open groups, Enter
+ * activates. New events bloom in while the rest glide; every move is an interruptible spring.
+ */
+export declare function activity(container: HTMLElement, options: ActivityOptions): Activity;

package/dist/types/ui/bento-css.d.ts

@@ -0,0 +1 @@
+export declare const bentoCss = "\n.knobs-ui.knobs-bento{--ku-bento-radius:var(--k-ui-bento-radius,max(0px,calc(var(--ku-radius) - 5px)));\n  position:relative;width:100%;height:100%;overflow:hidden auto;outline:none;background:var(--k-ui-bento-bg,var(--ku-page));\n  scrollbar-width:thin;scrollbar-gutter:stable;overscroll-behavior:contain;touch-action:pan-y;user-select:none;-webkit-user-select:none;\n  font:var(--ku-font-weight) var(--ku-font-size)/1.35 var(--ku-font);color:var(--ku-text);letter-spacing:normal;text-align:left}\n.knobs-bento[data-frame=\"flat\"]{--ku-bento-radius:var(--k-ui-bento-radius,0px)}\n.knobs-bento[data-pending] .knobs-bento-space{visibility:hidden}\n:where(.knobs-bento-space,.knobs-bento-space *){box-sizing:border-box}\n.knobs-bento-space{position:relative;width:100%}\n.knobs-bento-tile{position:absolute;left:0;top:0;transform-origin:0 0;overflow:hidden;border-radius:var(--ku-bento-radius);\n  background:var(--ku-surface);contain:strict;cursor:zoom-in}\n.knobs-bento-tile[data-focus]{z-index:2;cursor:zoom-out}\n.knobs-bento-tile[data-focus][data-live]{cursor:auto}\n.knobs-bento-img{display:block;width:100%;height:100%;object-fit:cover;opacity:0;transition:opacity .18s cubic-bezier(.2,.8,.2,1);-webkit-user-drag:none}\n.knobs-bento-tile[data-ready] .knobs-bento-img{opacity:1}\n.knobs-bento-tile[data-instant] .knobs-bento-img{transition:none}\n.knobs-bento-body{position:absolute;inset:0;pointer-events:none}\n.knobs-bento-tile[data-focus] .knobs-bento-body{pointer-events:auto}\n.knobs-bento-label{position:absolute;left:9px;right:9px;bottom:7px;color:#fff;font-size:var(--ku-text-meta);line-height:1.3;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;\n  text-shadow:0 0 6px rgba(0,0,0,.55),0 0 1px rgba(0,0,0,.5);opacity:0;pointer-events:none;transition:opacity calc(var(--ku-hover-out) * 1ms)}\n.knobs-bento:not([data-keyboard]) .knobs-bento-tile:hover .knobs-bento-label,\n.knobs-bento[data-keyboard]:focus .knobs-bento-tile[data-active] .knobs-bento-label,\n.knobs-bento-tile[data-focus] .knobs-bento-label{opacity:1;transition-duration:calc(var(--ku-hover-in) * 1ms)}\n/* A pick: a small dot in the accent, ringed in the page so it reads on any picture. */\n.knobs-bento-tile::after{content:\"\";position:absolute;top:8px;right:8px;width:8px;height:8px;border-radius:50%;background:var(--ku-accent);\n  box-shadow:0 0 0 1.5px color-mix(in srgb,var(--ku-page) 70%,transparent);opacity:0;scale:.4;pointer-events:none;\n  transition:opacity .11s cubic-bezier(.4,0,1,1),scale var(--ku-ease-ms) var(--ku-ease)}\n.knobs-bento-tile[aria-selected=\"true\"]::after{opacity:1;scale:1;transition:opacity .15s cubic-bezier(.2,.8,.2,1),scale var(--ku-ease-ms) var(--ku-ease)}\n.knobs-bento-wash{position:absolute;left:0;top:0;width:100px;height:100px;transform-origin:0 0;z-index:3;pointer-events:none;border-radius:var(--ku-bento-radius);\n  background:color-mix(in srgb,var(--ku-accent) 12%,transparent);box-shadow:inset 0 0 0 1px color-mix(in srgb,var(--ku-accent) 45%,transparent);\n  opacity:0;transition:opacity .15s}\n.knobs-bento[data-keyboard]:focus:not([data-zoomed]) .knobs-bento-wash[data-on]{opacity:1}\n.knobs-bento-scrim{position:absolute;left:0;top:0;width:100%;z-index:1;background:var(--k-ui-scrim,var(--k-ui-bento-bg,var(--ku-page)));opacity:0;pointer-events:none;cursor:zoom-out}\n.knobs-bento[data-zoomed] .knobs-bento-scrim{pointer-events:auto}\n.knobs-bento-head{position:absolute;left:0;top:0;display:flex;align-items:flex-end;padding:0 0 6px 2px;color:var(--ku-label);font-weight:var(--ku-label-weight);\n  font-size:var(--ku-text-meta);white-space:nowrap;pointer-events:none}\n";

package/dist/types/ui/bento-model.d.ts

@@ -0,0 +1,96 @@
+export interface BentoRect {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+/**
+ * `fit`: everything on one screen in justified rows. `hero`: one screen, one tile large beside or
+ * above the rest. `rows`: justified rows that scroll.
+ */
+export type BentoMode = "fit" | "hero" | "rows";
+export interface BentoPlan {
+    readonly mode: BentoMode;
+    /** One per item, in the items' order, in content coordinates. */
+    readonly rects: readonly BentoRect[];
+    readonly width: number;
+    /** The content's height: the view's in `fit` and `hero`, every row's in `rows`. */
+    readonly height: number;
+    /** Tile area over the area it lays out in (the view for one screen, the content for rows). */
+    readonly coverage: number;
+    /** The most any tile is cropped: its shown aspect over its own, less one (0: none). */
+    readonly crop: number;
+    /** Group headings (`rows` with groups): the group, its top and the first item's index. */
+    readonly headers: readonly {
+        readonly group: string;
+        readonly y: number;
+        readonly index: number;
+    }[];
+}
+export interface BentoLayout {
+    /** The view's size. */
+    readonly width: number;
+    readonly height: number;
+    /** Between tiles (2). */
+    readonly gap?: number;
+    /** Around the tiles (the gap). */
+    readonly padding?: number;
+    /** How far a tile may be cropped to fill a row, as a fraction of its width (.08). */
+    readonly tolerance?: number;
+    /** Scrolling rows' target height (about a third of the view, 120–420). */
+    readonly rowHeight?: number;
+    /** Whether a few items may lay out on one screen (true). */
+    readonly fit?: boolean;
+    /** The shortest a tile may be on one screen before the set scrolls instead (a sixth of the view, at least 80). */
+    readonly minTile?: number;
+    /** One per item: items with the same group sit together under its heading (scrolling rows). */
+    readonly groups?: readonly (string | undefined)[];
+    /** Heading height for groups (28). */
+    readonly header?: number;
+    /** An item that asks to be the hero; otherwise the first item becomes one when that shows more. */
+    readonly hero?: number;
+}
+/** Above this many items, sets scroll rather than fit one screen. */
+export declare const FIT_MAX = 24;
+/** Scrolling rows' target height for a view. */
+export declare const rowTarget: (width: number, height: number) => number;
+interface Row {
+    start: number;
+    end: number;
+    h: number;
+    /** Widths, one per item. */
+    ws: number[];
+}
+/**
+ * Greedy justified rows: items join a row until it would be shorter than `target`, and the row
+ * ends at whichever count lands nearer the target. Every full row spans the width at its own
+ * height, so nothing is cropped. A row only looks at items from its own start, so a change never
+ * moves the rows before it. The last row spans the width when that leaves it no more than a
+ * quarter taller than the target, or when cropping its tiles within `tol` fills it; otherwise it
+ * stays at the target height, left-aligned.
+ */
+export declare function justify(aspects: readonly number[], start: number, end: number, width: number, target: number, gap: number, tol: number): Row[];
+/** Splits `xs` in order into `k` runs whose largest total is as small as possible. */
+export declare function partition(xs: readonly number[], k: number): number[];
+/**
+ * Plans the tiles for a view. A set of up to `FIT_MAX` items lays out on one screen when its
+ * smallest tile stays at least `minTile` tall: as justified rows (the row count that shows the
+ * most), or with a hero when one is asked for or the first item as a hero shows 4% more. Larger
+ * sets, groups and narrow views scroll in greedy justified rows near `rowHeight`. Tiles keep their
+ * own aspect except where a crop within `tolerance` fills a row.
+ */
+export declare function planBento(aspects: readonly number[], layout: BentoLayout): BentoPlan;
+/** The indices whose rects meet `top…bottom`; `rows` plans are in reading order, so this bisects. */
+export declare function windowOf(plan: BentoPlan, top: number, bottom: number): number[];
+export type BentoDirection = "left" | "right" | "up" | "down";
+/**
+ * The tile an arrow reaches, by geometry. Left and right step along the row and wrap to the next
+ * or previous item at its ends; up and down go to the nearest row that way and the tile there
+ * whose centre is closest. Returns `from` when there's nowhere to go.
+ */
+export declare function neighbour(rects: readonly BentoRect[], from: number, dir: BentoDirection): number;
+/** `rect` fitted inside `w × h` at `aspect`, centred, `inset` from the edges. */
+export declare function fitRect(aspect: number, w: number, h: number, inset?: number): BentoRect;
+/** Motion blur for a tile moving at `speed` px/s: rises with speed to `max`, 0 below a crawl. */
+export declare function motionBlur(speed: number, max?: number, per?: number): number;
+export {};