@kitlangton/knobs 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,15 @@
+/**
+ * Places a segmented control's selected pill (`.knobs-seg-pill`) under the button whose
+ * `data-value` is `value`. The pill is placed by its edges so the edge facing the move can lead
+ * (see .knobs-seg-pill); a resize (a token gliding) carries it with its option instead of
+ * animating it, and the first placement doesn't animate. With no matching button the pill fades.
+ * While a pan holds the pill (see `panOptions`), it stays with the fingers. Showing the value it
+ * already shows reads no layout (a resize, `resized`, re-places it).
+ */
+export declare function placeSegPill(seg: HTMLElement, buttons: readonly HTMLButtonElement[], value: string, resized?: boolean): void;
+/**
+ * Reads where each option sits ahead of a batch's writes (see measure.ts), while layout is still
+ * clean: choosing an option doesn't move any, so the pill then places without reading layout
+ * after the batch has dirtied it.
+ */
+export declare function primeSegPill(seg: HTMLElement, buttons: readonly HTMLElement[]): void;

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

@@ -0,0 +1,21 @@
+/** What a reload should bring back, per tab: open panels, open editors and the focused stop. */
+export interface PanelSession {
+    readonly open?: boolean;
+    readonly expanded?: readonly string[];
+    readonly focus?: {
+        readonly inline: boolean;
+        readonly stop: number;
+    };
+    /** A page's collapsible custom cards, by title: whether each is folded. */
+    readonly folded?: Readonly<Record<string, boolean>>;
+    /** A panel's foldable groups, by id: whether each is folded. */
+    readonly groups?: Readonly<Record<string, boolean>>;
+    /** A panel's sub-headings, by group and name: whether each is folded. */
+    readonly subsections?: Readonly<Record<string, boolean>>;
+    /** The tab a panel showed. */
+    readonly tab?: string;
+}
+/** The tab's sessionStorage, where there is one. */
+export declare const tabStorage: () => Storage | null;
+export declare function readSession(id: string): PanelSession;
+export declare function writeSession(id: string, patch: Partial<PanelSession>): void;

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

@@ -0,0 +1,92 @@
+import type { Knob as KnobField } from "../core/schema.js";
+import { Roll, Spring, VelocityTracker } from "./motion.js";
+export interface DigitPlace {
+    ch: string;
+    /** Unbounded wheel position for digits (… 9, 10, 11 …); face = position mod 10. */
+    readonly wheel: Roll;
+    /** 1 while shown, 0 once gone: new places fade in and rise, leaving places fade out. */
+    readonly presence: Roll;
+    /** When this place started entering, and how long the entrance lasts (ms). */
+    enterAt: number;
+    enterMs: number;
+    exiting: boolean;
+}
+export interface Slider {
+    element: HTMLElement;
+    /** The focusable, keyboard-driven surface. */
+    track: HTMLElement;
+    /** The visible label element. */
+    label: HTMLElement;
+    /** The value button element. */
+    valueButton: HTMLButtonElement;
+    /** The inline number editor (hidden until the value is clicked). */
+    number: HTMLInputElement;
+    /**
+     * Spring driving the fill's edge [0..1]: the value, or while a stepped slider is in hand, the
+     * value pulled part way toward the pointer (--k-step-resist).
+     */
+    fillSpring: Spring;
+    /** Spring driving handle visibility/scale [0..1] (the GPU renderer sets its target). */
+    handleSpring: Spring;
+    /** Per-character springs for GPU rolling number digits. */
+    /** Readout characters keyed by place from the right, so 99 → 100 keeps the 9s in place. */
+    digitPlaces: DigitPlace[];
+    /** Velocity tracker on normalized fill ratio for drag motion blur. */
+    velocity: VelocityTracker;
+    /** Number of tick marks along the track. */
+    readonly tickCount: number;
+    /** Where the default value sits along the track [0..1]. */
+    readonly notchRatio: number;
+    /** Whether a drag is currently held on the default by the notch's magnet. */
+    isMagnetized(): boolean;
+    /** When the readout last popped (a click landing on a decile, or the default's magnet). */
+    poppedAt: number;
+    /** Formatted numeric string without unit (e.g. "0.45" or "98"). */
+    getDigitsText(): string;
+    /** Optional unit string (e.g. "px", "s"). */
+    getUnitText(): string;
+    /** Whether pointer drag is currently active. */
+    isDragging(): boolean;
+    /** Whether the inline number input is open. */
+    isEditing(): boolean;
+    /**
+     * `delay` (ms) holds this row's motion for its turn in a preset cascade; `instant` places the
+     * value without springing or rolling (a different item arrived).
+     */
+    update(value: number, delay?: number, instant?: boolean): void;
+    /**
+     * Reads its design tokens now. A batch (a preset) primes every row it will move before writing
+     * any, so no row's read lands after another's writes and forces a style pass.
+     */
+    prime(): void;
+    /** Takes a new range, step, label or unit in place, keeping the DOM (see `RemoteControls.update`). */
+    retune(field: KnobField): void;
+    /** The field it currently draws. */
+    readonly field: KnobField;
+    /** Open the inline editor, with `initial` in place of the value (a digit typed on the track). */
+    edit(initial?: string): void;
+    /** Puts a row accessory just after the label; the ticks and handle keep clear of it too. */
+    slot(node: HTMLElement): void;
+    dispose(): void;
+}
+export declare const decimals: (step: number) => number;
+/**
+ * `steps` grid steps from `value` (negative goes down), on the slider's grid counted from `min`.
+ * From a value between grid points (a declared default like 0.4 on a 0.02 grid from 0.15) the
+ * first step lands on the next grid point that way, not past it.
+ */
+export declare function stepValue(field: {
+    min: number;
+    max: number;
+    step: number;
+}, value: number, steps: number): number;
+/**
+ * A DialKit-style slider: the whole row is the track, the fill is a full-height block,
+ * the handle is a hairline that only shows on hover, and the label + value sit on the
+ * track itself. Dragging follows the pointer exactly (⌥ for 1/10 speed) and the default's notch
+ * pulls it in from a few px away; a click snaps to the nearest step (or nearest 10% when there
+ * are many steps) with a short spring-like ease. A sideways trackpad pan moves it like a drag.
+ */
+export declare function createSlider(doc: Document, key: string, initialField: KnobField, set: (value: number, options?: {
+    coalesce?: boolean;
+}) => void, onMotionWake?: () => void): Slider;

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

@@ -0,0 +1,7 @@
+/** Smears `pill` by its speed while it glides: `cap` is the widest smear (px), as on the GPU. */
+export declare function smearPill(pill: HTMLElement, cap: number): void;
+/**
+ * How wide a range band's end smears (px) at `speed` px/s, by `strength` (--k-range-blur, 0 to 1):
+ * the slider fill's edge ramp, so both read alike. 0 under a quarter pixel, so it rests crisp.
+ */
+export declare function rangeSmear(speed: number, strength: number): number;

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

@@ -0,0 +1,13 @@
+/**
+ * One more turn for the ↺ in `button` (its first `.knobs-icon`), from wherever it is now; `rest`
+ * runs once it has stopped.
+ */
+export declare function spin(button: HTMLElement, wake?: () => void, rest?: () => void): void;
+/** Whether `button`'s ↺ is turning (or blinking). */
+export declare const spinning: (button: Element) => boolean;
+/** Where `button`'s ↺ is now, for the GPU renderer: its turn (radians, clockwise) and opacity. */
+export declare function spinOf(button: Element, now: number): {
+    angle: number;
+    alpha: number;
+    moving: boolean;
+};

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

@@ -0,0 +1,11 @@
+import { type TokenPreset } from "../core/theme.js";
+/**
+ * What DELAY times: a row's turn in a preset's cascade is set on these (see `showValues` in
+ * panel.ts) rather than on the row, where the custom property would restyle all of the row.
+ */
+export declare const DELAYED = ".knobs-fill,.knobs-handle,.knobs-seg-pill,.knobs-toggle,.knobs-toggle i,.knobs-arm,.knobs-curve,.knobs-swatch,.knobs-strip-thumb,.knobs-pad>i,.knobs-ease-handle,.knobs-range-fill,.knobs-range-thumb,.knobs-dial-hand,.knobs-grad,.knobs-grad-mini,.knobs-grad-mini>i,.knobs-grad-stop,.knobs-graph-pt";
+/** Adds a token preset's stylesheet once per document. */
+export declare function injectPreset(doc: Document, preset: TokenPreset): void;
+/** The rules' `:has()` as the attributes has.ts keeps (see there for why). */
+export declare const withoutHas: (css: string) => string;
+export declare function injectStyles(doc: Document): void;

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/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/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 {};