@exponential_app/eui 0.3.0 → 0.4.0

package/dist/types/src/web/primitives/zoomable-image.d.ts

@@ -0,0 +1,158 @@
+import type * as Zoom from "../../zoom.js";
+import type { ZoomFrame, ZoomInitial, ZoomSize, ZoomView } from "../../zoom.js";
+type Core = typeof Zoom;
+/** The core functions the controller drives (`@exponential_app/eui`). */
+export type ZoomMath = Pick<Core, `ZOOM` | `zoomIsTall` | `zoomRestView` | `zoomClamp` | `zoomAtRest` | `zoomTo` | `zoomCentre` | `zoomWheel` | `zoomScroll` | `zoomStep` | `zoomDoubleTap` | `zoomKey` | `zoomDrag` | `zoomPinch` | `zoomMomentum` | `zoomMomentumActive` | `zoomPanRoom` | `zoomResize` | `zoomPercent` | `zoomMenu` | `zoomBounds`>;
+export declare const ZOOM_CONTROLS: readonly ["auto", "always", "none"];
+export type ZoomControls = (typeof ZOOM_CONTROLS)[number];
+/** What the pill draws (changes only when one of these does). */
+export interface ZoomPillState {
+    percent: string;
+    atMin: boolean;
+    atMax: boolean;
+    atRest: boolean;
+}
+/** Two taps / clicks closer than this (ms, px) are a double tap. */
+export declare const ZOOM_DOUBLE_TAP_MS = 300;
+export declare const ZOOM_DOUBLE_TAP_SLOP = 24;
+/** A press that moves less than this (px) is a tap, not a drag. */
+export declare const ZOOM_TAP_SLOP = 4;
+/** A ⌘/ctrl-wheel run settles (fires `zoom`) after this idle (ms). */
+export declare const ZOOM_WHEEL_SETTLE_MS = 150;
+/** The box's CSS aspect ratio (w/h): the picture's own, capped at the width
+ *  for a TALL picture (a square window onto its top), else 16:9; none when
+ *  the style sets a height. */
+export declare function zoomBoxAspect(math: Pick<ZoomMath, `zoomIsTall`>, natural: ZoomSize | null, styledHeight: boolean): number | null;
+/** The natural size the props declare (both positive), else null. */
+export declare function zoomDeclaredSize(width: unknown, height: unknown): ZoomSize | null;
+/** The menu's items (Fit, then the presets inside the limits) for the
+ *  current view, before the controller measured (the rest view's). */
+export declare function zoomPillOf(math: ZoomMath, view: ZoomView, frame: ZoomFrame): ZoomPillState;
+export interface ZoomControllerOptions {
+    math: ZoomMath;
+    /** The viewport: focusable, takes every gesture. */
+    root: HTMLElement;
+    /** The picture, transformed (`transform-origin: 0 0`). */
+    image: HTMLElement;
+    /** The zoom pill (its hover / focus keep it shown); null = none. */
+    pill: () => HTMLElement | null;
+    /** The picture's pixel size, null while unknown. */
+    natural: () => ZoomSize | null;
+    initial: () => ZoomInitial;
+    maxScale: () => number | undefined;
+    /** The scale the host binds (`scale`), undefined = the rest view. */
+    boundScale: () => number | undefined;
+    /** The CSS `transition` of an animated change (the theme's standard
+     *  motion); null = snap (reduced motion). */
+    transition: () => string | null;
+    /** `controls: auto` (the pill hides on its own). */
+    autoHide: () => boolean;
+    onPill: (pill: ZoomPillState) => void;
+    onPillVisible: (visible: boolean) => void;
+    /** A settled zoom change. */
+    onZoom: (scale: number, atFit: boolean) => void;
+    /** A single tap / click at rest. */
+    onTap: () => void;
+}
+export interface ZoomController {
+    view: () => ZoomView;
+    frame: () => ZoomFrame | null;
+    /** The pill's − / +. */
+    step: (direction: 1 | -1) => void;
+    /** Back to the rest view (the fit button, the menu's Fit). */
+    rest: () => void;
+    /** To `scale` about the viewport centre (the menu's presets). */
+    zoomScale: (scale: number) => void;
+    /** The bound `scale` changed from outside: apply it, no event. */
+    syncScale: () => void;
+    /** A new picture / natural size / initial / max: the rest view, at once. */
+    reset: () => void;
+    /** Keep the pill shown (its menu is open). */
+    holdPill: (hold: boolean) => void;
+    destroy: () => void;
+}
+/** Binds the gestures to `root` and paints `image`; the pill's state and
+ *  visibility go out through the callbacks. Every number comes from the
+ *  core's functions. */
+export declare function createZoomController(o: ZoomControllerOptions): ZoomController;
+/** The native's LAYOUT (inline: the theme recipe styles every part, these
+ *  only place them; React style objects, Solid passes them through `css`).
+ *  `pill` = style.json `zoomableImage.pill`. `flexShrink` comes last: jsdom
+ *  re-appends it when Solid re-applies a style, so React's order holds. */
+export declare function zoomableImageLayout(pill: {
+    inset: number;
+    percentMinWidth: number;
+}): {
+    readonly root: {
+        readonly overflow: "clip";
+        readonly userSelect: "none";
+    };
+    readonly image: {
+        readonly position: "absolute";
+        readonly left: 0;
+        readonly top: 0;
+        readonly display: "block";
+        readonly maxWidth: "none";
+        readonly maxHeight: "none";
+        readonly transformOrigin: "0 0";
+        readonly pointerEvents: "none";
+        readonly userSelect: "none";
+    };
+    readonly pill: {
+        readonly position: "absolute";
+        readonly left: "50%";
+        readonly bottom: number;
+        readonly transform: "translateX(-50%)";
+        readonly zIndex: 1;
+        readonly display: "flex";
+        readonly flexDirection: "row";
+        readonly alignItems: "center";
+        readonly whiteSpace: "nowrap";
+        readonly cursor: "default";
+        readonly transition: "opacity var(--xui-motion-standard) var(--xui-ease-standard,ease)";
+    };
+    readonly pillHidden: {
+        readonly opacity: 0;
+        readonly pointerEvents: "none";
+    };
+    readonly button: {
+        readonly display: "inline-flex";
+        readonly alignItems: "center";
+        readonly justifyContent: "center";
+        readonly cursor: "pointer";
+        readonly flexShrink: 0;
+    };
+    readonly percent: {
+        readonly display: "inline-flex";
+        readonly alignItems: "center";
+        readonly justifyContent: "center";
+        readonly cursor: "pointer";
+        readonly minWidth: number;
+        readonly fontVariantNumeric: "tabular-nums";
+        readonly flexShrink: 0;
+    };
+    readonly divider: {
+        readonly alignSelf: "center";
+        readonly flexShrink: 0;
+    };
+};
+/** The settle spring of the native (the theme's standard motion). */
+export declare const ZOOMABLE_IMAGE_NATIVE_TRANSITION = "transform var(--xui-motion-standard) var(--xui-ease-standard,ease)";
+/** The primitive's (the app's motion tokens). */
+export declare const ZOOMABLE_IMAGE_TRANSITION = "transform var(--motion-duration-standard,var(--xui-duration-standard,180ms)) var(--motion-ease-standard,cubic-bezier(0.2,0,0,1))";
+/** The primitive's picture style before the controller paints it. */
+export declare function zoomImageStyle(natural: ZoomSize | null): Record<string, string | number>;
+export declare const ZOOMABLE_IMAGE_CLASSES: {
+    /** The viewport: as wide as its parent, the picture clipped to it. */
+    readonly root: "relative w-full min-w-0 overflow-hidden rounded-md select-none outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50";
+    readonly image: "pointer-events-none absolute top-0 left-0 block max-h-none max-w-none origin-top-left select-none";
+    /** THE pill: one glass capsule bottom-centre, `pill.inset` above the edge. */
+    readonly pill: "absolute bottom-4 left-1/2 z-10 flex -translate-x-1/2 flex-row items-center gap-0.5 rounded-full border border-glass-stroke-card bg-popover p-1 whitespace-nowrap shadow-lg backdrop-blur-lg transition-opacity duration-standard ease-standard";
+    readonly pillHidden: "pointer-events-none opacity-0";
+    /** − / + / fit: ghost icon buttons, 28 px circles (no border or fill of
+     *  their own where the host has no preflight). */
+    readonly button: "size-7 rounded-full border-0 bg-transparent";
+    readonly percent: "h-7 min-w-14 rounded-full border-0 bg-transparent px-2 tabular-nums";
+    readonly divider: "mx-0.5 h-4 w-px shrink-0 bg-border";
+};
+export {};

package/dist/types/src/web/table.d.ts

@@ -11,7 +11,15 @@ export interface TableColumn {
     width?: number;
     align?: `start` | `center` | `end`;
     sortable?: boolean;
+    /** EXP-1548: one line with an ellipsis; cells wrap otherwise. */
+    truncate?: boolean;
 }
+/** Every row's grid columns (round 2 §7): a fixed `width` keeps its px, the
+ *  rest share the width, EXP-1548: never under `tableColumnMin`. */
+export declare function tableTemplate(columns: readonly TableColumn[], multiple: boolean): string;
+/** EXP-1548: the narrowest the columns fit in: header and body are at least
+ *  this wide, so a narrower table scrolls (its root is the scroller). */
+export declare function tableMinWidth(columns: readonly TableColumn[], multiple: boolean): string;
 export interface TableSort {
     key: string;
     direction: `asc` | `desc`;

package/dist/types/src/zoom.d.ts

@@ -0,0 +1,128 @@
+export declare const ZOOM: {
+    $comment: string;
+    tallAspect: number;
+    maxScale: number;
+    presets: number[];
+    menuPresets: number[];
+    doubleTapFactor: number;
+    wheelRate: number;
+    wheelLinePx: number;
+    rubber: number;
+    momentumTauMs: number;
+    autoHideMs: number;
+    pill: {
+        height: number;
+        inset: number;
+        padding: number;
+        gap: number;
+        percentMinWidth: number;
+        dividerHeight: number;
+    };
+};
+export type ZoomInitial = `auto` | `fit` | `fitWidth` | `actual`;
+export interface ZoomSize {
+    width: number;
+    height: number;
+}
+export interface ZoomPoint {
+    x: number;
+    y: number;
+}
+/** scale = displayed px per image px (1 = 100%); x/y = the picture's
+ *  top-left in the viewport. */
+export interface ZoomView {
+    scale: number;
+    x: number;
+    y: number;
+}
+/** What every function needs to know about the picture and its box. */
+export interface ZoomFrame {
+    natural: ZoomSize;
+    viewport: ZoomSize;
+    initial?: ZoomInitial;
+    maxScale?: number;
+}
+/** A picture taller than 1 / tallAspect times its width. */
+export declare function zoomIsTall(natural: ZoomSize): boolean;
+/** The whole picture inside the viewport, never upscaled: the minimum. */
+export declare function zoomFitScale(frame: ZoomFrame): number;
+/** The scale range: [fit, max(fit, maxScale)]. */
+export declare function zoomLimits(frame: ZoomFrame): {
+    min: number;
+    max: number;
+};
+/** The scale the picture opens at (and a double tap / `0` / the fit button
+ *  returns to), inside the limits. */
+export declare function zoomRestScale(frame: ZoomFrame): number;
+/** The view inside its bounds (scale within the limits, no letterbox). */
+export declare function zoomClamp(view: ZoomView, frame: ZoomFrame): ZoomView;
+/** The opening view: the rest scale, centred; a taller-than-the-viewport
+ *  picture starts at its top. */
+export declare function zoomRestView(frame: ZoomFrame): ZoomView;
+/** Whether the view sits at its rest scale. */
+export declare function zoomAtRest(view: ZoomView, frame: ZoomFrame): boolean;
+/** Zoom to `scale` (clamped) keeping the image point under `anchor` fixed. */
+export declare function zoomTo(view: ZoomView, scale: number, anchor: ZoomPoint, frame: ZoomFrame): ZoomView;
+/** The viewport's centre, the anchor of keys and the pill. */
+export declare function zoomCentre(frame: ZoomFrame): ZoomPoint;
+export type WheelDeltaMode = `pixel` | `line`;
+/** ⌘/ctrl + wheel (or a trackpad pinch delivered as a wheel): the scale
+ *  factor of one wheel event. */
+export declare function zoomWheelFactor(deltaY: number, mode?: WheelDeltaMode): number;
+/** One ⌘/ctrl-wheel event about the cursor. */
+export declare function zoomWheel(view: ZoomView, deltaY: number, mode: WheelDeltaMode, anchor: ZoomPoint, frame: ZoomFrame): ZoomView;
+/** A plain wheel / two-finger scroll: pans by the deltas, clamped. */
+export declare function zoomScroll(view: ZoomView, deltaX: number, deltaY: number, frame: ZoomFrame): ZoomView;
+/** The ladder steps walk: the presets plus the rest scale, inside the
+ *  limits, ascending. */
+export declare function zoomLadder(frame: ZoomFrame): number[];
+/** The next ladder scale strictly above (`1`) or below (`-1`) the current
+ *  one, or the current one at the end. */
+export declare function zoomStepScale(scale: number, direction: 1 | -1, frame: ZoomFrame): number;
+/** + / − (keys and the pill) about the viewport centre. */
+export declare function zoomStep(view: ZoomView, direction: 1 | -1, frame: ZoomFrame): ZoomView;
+/** The scale a double tap at rest jumps to. */
+export declare function zoomDoubleTapScale(frame: ZoomFrame): number;
+/** Double click / tap: at rest → zoom in about the point; else → rest. */
+export declare function zoomDoubleTap(view: ZoomView, point: ZoomPoint, frame: ZoomFrame): ZoomView;
+export type ZoomKey = `+` | `=` | `-` | `−` | `0` | `1`;
+/** A key while the picture has focus; null = not a zoom key. */
+export declare function zoomKey(view: ZoomView, key: string, frame: ZoomFrame): ZoomView | null;
+/** The overshoot past an edge, damped: (1 − 1 / (o·c/d + 1))·d. */
+export declare function zoomRubberBand(overshoot: number, extent: number): number;
+/** A drag from `start` by (dx, dy) while held: past an edge the overshoot
+ *  rubber-bands. The release is `zoomClamp` of the last view. */
+export declare function zoomDrag(start: ZoomView, dx: number, dy: number, frame: ZoomFrame): ZoomView;
+/** A pinch from `start` by the raw factor about `anchor` while held: past
+ *  the min/max the scale rubber-bands (d = the limit). The release is
+ *  `zoomClamp` of the last view. */
+export declare function zoomPinch(start: ZoomView, factor: number, anchor: ZoomPoint, frame: ZoomFrame): ZoomView;
+/** Mouse-drag momentum `t` ms after a release at velocity (px/ms),
+ *  exponential decay, stopping at the edges. */
+export declare function zoomMomentum(view: ZoomView, vx: number, vy: number, t: number, frame: ZoomFrame): ZoomView;
+/** Whether momentum `t` ms after a release is still moving (above 0.01 px/ms). */
+export declare function zoomMomentumActive(vx: number, vy: number, t: number): boolean;
+/** The axes the picture can pan on: an axis without room hands a swipe to
+ *  the host (paging). */
+export declare function zoomPanRoom(view: ZoomView, frame: ZoomFrame): {
+    x: boolean;
+    y: boolean;
+};
+/** A new viewport: at rest = the new rest view; zoomed = the same scale
+ *  about the viewport centre, clamped. */
+export declare function zoomResize(view: ZoomView, from: ZoomSize, frame: ZoomFrame): ZoomView;
+/** The pill's label: round(scale × 100) + `%`. */
+export declare function zoomPercent(scale: number): string;
+export interface ZoomMenuItem {
+    /** null = Fit (the rest view). */
+    scale: number | null;
+    label: string;
+    checked: boolean;
+}
+/** The % button's Menu: Fit, then the menu presets inside the limits. */
+export declare function zoomMenu(view: ZoomView, frame: ZoomFrame, fitLabel: string): ZoomMenuItem[];
+/** The pill's disabled ends. */
+export declare function zoomBounds(view: ZoomView, frame: ZoomFrame): {
+    atMin: boolean;
+    atMax: boolean;
+};