jaml-ui 4.3.1 → 4.6.0

package/dist/ui/JimboApp.d.ts

@@ -1,15 +1,17 @@
 import { HTMLAttributes, ReactNode } from 'react';
-export type JimboAppVariant = "embed" | "page";
+export type JimboAppVariant = "embed" | "phone" | "page";
 export interface JimboAppProps extends HTMLAttributes<HTMLDivElement> {
-    /** embed = fixed 320×540 MCP shell; page = fluid full-viewport web shell */
+    /** embed = MCP-on-desktop 375×375 square. phone = locked portrait. page = full website. */
     variant?: JimboAppVariant;
-    /** Main column. For embed, scrolls inside the fixed frame when scroll is true. */
+    /** Main column. For embed/phone, scrolls inside the frame when true. */
     scroll?: boolean;
     footer?: ReactNode;
 }
 /**
- * App chrome. Embed = Balatro-toy / MCP rectangle. Page = fan-site / seedfinder shell.
- * Both set the Jimbo font stack and color; neither paints a second background
- * (use JimboBackground behind).
+ * App chrome.
+ * embed = MCP host iframe (square, funny on purpose).
+ * phone = mobile portrait, 375×667 (iPhone SE) / 100dvh — not the MCP square.
+ * page = desktop website, full viewport.
+ * None paints a second background (use JimboBackground behind).
  */
 export declare function JimboApp({ variant, scroll, footer, className, children, ...rest }: JimboAppProps): import("react").JSX.Element;

package/dist/ui/JimboBackground.d.ts

@@ -1,15 +1,7 @@
-import { default as React } from 'react';
+import { JimboBackgroundConfig } from './hooks.js';
+export type { JimboBackgroundConfig, JimboBackgroundColor } from './hooks.js';
 /**
- * Fullscreen WebGL CRT/spin background — the authentic Balatro hypnotic
- * swirl, pixelated and animated. Ported from weejoker.app's
- * BackgroundShader.tsx; no config required.
- *
- * Renders a fixed-position canvas at z-index: -10 that fills the viewport
- * and ignores pointer events. Drop it once at the root of your page:
- *
- *     <JimboBackground />
- *     <YourAppContent />
- *
- * Resizes automatically. Disposes the animation frame + shader on unmount.
+ * Fullscreen WebGL CRT/spin background. Shader knobs are uniforms
+ * (`useBalatroBackground`) so Storybook can drive swirl / pixel / RGB.
  */
-export declare function JimboBackground(): React.JSX.Element;
+export declare function JimboBackground(config?: JimboBackgroundConfig): import("react").JSX.Element;

package/dist/ui/JimboBox.d.ts

@@ -0,0 +1,16 @@
+import { default as React } from 'react';
+export interface JimboBoxProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Render as a different element (default: div) */
+    as?: "div" | "section" | "article" | "aside" | "main" | "nav" | "header" | "footer";
+    children?: React.ReactNode;
+}
+/**
+ * Thin wrapper around `<div>` (or another block element).
+ *
+ * All consumer code outside `src/ui/` must use `JimboBox` instead of raw
+ * `<div>` — the ESLint `no-raw-html` rule forbids intrinsic HTML elements.
+ * This component exists so that layouts can still use a plain container
+ * without reaching for a higher-level primitive that adds semantics they
+ * don't need (e.g. `JimboPanel` implies a visible card).
+ */
+export declare const JimboBox: React.ForwardRefExoticComponent<JimboBoxProps & React.RefAttributes<HTMLDivElement>>;

package/dist/ui/JimboButton.d.ts

@@ -1,7 +1,7 @@
 import { ButtonHTMLAttributes } from 'react';
 export interface JimboButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
     size?: "xs" | "sm" | "md" | "lg";
-    tone?: "orange" | "red" | "blue" | "green";
+    tone?: "orange" | "red" | "blue" | "green" | "purple" | "grey";
     fullWidth?: boolean;
     label?: string;
 }

package/dist/ui/JimboCanvas.d.ts

@@ -0,0 +1,12 @@
+import { default as React } from 'react';
+export interface JimboCanvasProps extends React.CanvasHTMLAttributes<HTMLCanvasElement> {
+    children?: React.ReactNode;
+}
+/**
+ * Thin wrapper around `<canvas>`.
+ *
+ * Used by `CanvasRenderer` and any other component that needs a raw
+ * drawing surface. The ESLint `no-raw-html` rule forbids `<canvas>`
+ * outside `src/ui/`, so consumers use this primitive instead.
+ */
+export declare const JimboCanvas: React.ForwardRefExoticComponent<JimboCanvasProps & React.RefAttributes<HTMLCanvasElement>>;

package/dist/ui/JimboDock.d.ts

@@ -0,0 +1,21 @@
+import { ReactNode } from 'react';
+import { JimboOuterTabTone } from './JimboOuterTab.js';
+export { defaultPyramidDock, dockActivate, type DockNode, } from './dockTree.js';
+export interface JimboDockPane {
+    label: string;
+    tone: JimboOuterTabTone;
+    content: ReactNode;
+}
+export interface JimboDockProps {
+    panes: Record<string, JimboDockPane>;
+    /** Filter / search / results / jamlyze keys for the pyramid default. */
+    pyramid?: {
+        filter: string;
+        search: string;
+        results: string;
+        jamlyze: string;
+    };
+    storageKey?: string;
+    className?: string;
+}
+export declare function JimboDock({ panes, pyramid, storageKey, className, }: JimboDockProps): import("react").JSX.Element;

package/dist/ui/JimboInline.d.ts

@@ -0,0 +1,11 @@
+import { default as React } from 'react';
+export interface JimboInlineProps extends React.HTMLAttributes<HTMLSpanElement> {
+    children?: React.ReactNode;
+}
+/**
+ * Thin wrapper around `<span>`.
+ *
+ * Use when you need an inline container that is not a `JimboText` (which
+ * applies typography tokens). For styled text, prefer `JimboText`.
+ */
+export declare function JimboInline({ children, ...rest }: JimboInlineProps): React.JSX.Element;

package/dist/ui/JimboLink.d.ts

@@ -0,0 +1,11 @@
+import { default as React } from 'react';
+export interface JimboLinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+    children?: React.ReactNode;
+}
+/**
+ * Thin wrapper around `<a>`.
+ *
+ * Use when you need a plain hyperlink. The ESLint `no-raw-html` rule
+ * forbids `<a>` outside `src/ui/`, so consumers use this primitive.
+ */
+export declare function JimboLink({ children, ...rest }: JimboLinkProps): React.JSX.Element;

package/dist/ui/JimboMascot.d.ts

@@ -1,12 +1,58 @@
-import { HTMLAttributes } from 'react';
+import { HTMLAttributes, ReactNode } from 'react';
 import { JimboOrbitalMenuItem } from './JimboOrbitalMenu.js';
+import { JimboOrbitalStore } from './orbitalMenuStore.js';
 export interface JimboMascotProps extends HTMLAttributes<HTMLDivElement> {
     mood?: "idle" | "happy" | "surprised";
     /** Box size in px. Default 96. */
     size?: number;
-    /** When present, tapping the mascot toggles a radial action menu. */
+    /** A flat ring, no submenus. Ignored when `getMenuItems` is given. */
     menuItems?: JimboOrbitalMenuItem[];
-    onMenuAction?: (action: string) => void;
+    /**
+     * Resolve the items for a menu path — `[]`, `["main"]`, `["main","Tools"]`.
+     *
+     * This is the seam that makes submenus, paging and the south exit the
+     * mascot's job rather than every consumer's. An item with a `submenu` pushes
+     * onto the path; one with an `action` fires `onMenuAction`.
+     */
+    getMenuItems?: (menuStack: string[]) => JimboOrbitalMenuItem[];
+    onMenuAction?: (action: string, item: JimboOrbitalMenuItem) => void;
+    /**
+     * Largest orbit radius the ring may use, px. Pass
+     * `maxOrbitRadiusForBox(w, h)` for the box the mascot is sectioned into and
+     * the ring can never overflow it, however many items a menu holds.
+     */
+    maxOrbitRadius?: number;
+    /**
+     * Height of the box the mascot is sectioned into, px. Pins the south button
+     * to the box's bottom edge at full width — Balatro's exit law — instead of
+     * letting it ride the orbit radius.
+     */
+    orbitBoxHeight?: number;
+    /**
+     * Width of that same box, px.
+     *
+     * Load-bearing whenever `orbitBoxHeight` is set: the ring measures the
+     * element it is drawn into, and left to itself that element is the mascot's
+     * own box — a couple of hundred pixels narrower than the territory the ring
+     * owns. Pills then have nowhere to fly out to and stack on the character.
+     * Give the ring the real square and it fills it.
+     *
+     * The ring is centered on the mascot, so place the mascot where the ring's
+     * center belongs — usually the middle of that square.
+     */
+    orbitBoxWidth?: number;
+    /** Orbit radius before item-count growth. Default 90. */
+    baseOrbitRadius?: number;
+    /** Keep the ring shut (an overlay owns the screen). */
+    menuHidden?: boolean;
+    /** South-button label at the root of the menu. Deeper in it always says Back. */
+    closeLabel?: string;
+    /** Use a private menu store instead of the shared one. */
+    orbitalStore?: JimboOrbitalStore;
+    /** Draw something else as the character — the artwork seam. */
+    renderImage?: (info: {
+        size: number;
+    }) => ReactNode;
 }
-/** Jammy, the seed mascot — bounces, shakes, and hosts a radial menu. */
-export declare function JimboMascot({ mood, size, menuItems, onMenuAction, className, ...rest }: JimboMascotProps): import("react").JSX.Element;
+/** Jammy, the seed mascot — bounces, shakes, and hosts the orbital menu. */
+export declare function JimboMascot({ mood, size, menuItems, getMenuItems, onMenuAction, maxOrbitRadius, orbitBoxHeight, orbitBoxWidth, baseOrbitRadius, menuHidden, closeLabel, orbitalStore, renderImage, className, ...rest }: JimboMascotProps): import("react").JSX.Element;

package/dist/ui/JimboOrbitalMenu.d.ts

@@ -1,15 +1,87 @@
-import { HTMLAttributes } from 'react';
-import { JimboBadgeTone } from './JimboBadge.js';
+import { ReactNode } from 'react';
+import { JimboStatus } from './JimboStatusPill.js';
+export type JimboOrbitalTone = "red" | "blue" | "orange" | "green" | "purple";
+/**
+ * Strict color semantics, carried over from the harvest because they are how
+ * the ring stays readable at a glance:
+ *
+ *   RED    submenu or plain action        ORANGE  toggle, and the way out
+ *   BLUE   talks to the assistant         GREEN   start (welcome screen only)
+ *   PURPLE a counted / tallied thing
+ */
 export interface JimboOrbitalMenuItem {
     label: string;
-    action: string;
-    tone?: JimboBadgeTone;
+    /** Emitted through `onAction`. Omit when `submenu` is set. */
+    action?: string;
+    /** Pushes a submenu of this name instead of firing an action. */
+    submenu?: string;
+    tone?: JimboOrbitalTone;
+    /** Present (even as `false`) makes this a toggle and draws the state dot. */
+    active?: boolean;
+    disabled?: boolean;
+    /** Draws a tally on the pill's right edge. */
+    count?: number;
+    /** Drawn in place of a count. */
+    icon?: ReactNode;
+    tooltip?: string;
+    /** Renders a non-interactive status pill instead of a button. */
+    badge?: {
+        label: string;
+        status: JimboStatus;
+    };
+    /**
+     * Pin to the south slot. That slot is the way out — Balatro's exit law is a
+     * full-width button along the very bottom at any modal size — so at most one
+     * item should carry it.
+     */
+    south?: boolean;
+    /** Render at lower opacity (unavailable, but worth showing). */
+    dim?: boolean;
 }
-export interface JimboOrbitalMenuProps extends HTMLAttributes<HTMLDivElement> {
+export interface JimboOrbitalMenuProps {
     items: JimboOrbitalMenuItem[];
-    onAction?: (action: string) => void;
-    /** Orbit radius in px. Default 90. */
+    onAction?: (action: string, item: JimboOrbitalMenuItem) => void;
+    /** Fired when a `submenu` item is clicked. */
+    onNavigate?: (submenu: string) => void;
+    /** Fired when the south item is clicked. */
+    onBack?: () => void;
+    /** Current menu name — keys the pills so a submenu push re-animates them. */
+    currentMenu?: string;
+    /** Collapse the pills to center (the close/push animation). */
+    closing?: boolean;
+    /** Mascot diameter (px). Pills are pushed out to clear it. */
+    mascotSize?: number;
+    /** Horizontal orbit radius (px). */
     radius?: number;
+    /** Vertical orbit radius (px). Defaults to `radius`. */
+    radiusY?: number;
+    /**
+     * Height of the box the ring is sectioned into (px).
+     *
+     * When given, geometry switches to THE ORBIT LAW (see ./orbitalLayout): pills
+     * stack by height and fly out to the walls, and the south button pins to the
+     * container's bottom edge at full width instead of riding the orbit. That is
+     * what makes the ring fit a short, wide box without shrinking the mascot.
+     */
+    boxHeight?: number;
+    /** Vertical shift (px) — hosts use it to dodge an on-screen keyboard. */
+    translateY?: number;
+    /** Rendered above the south button. */
+    breadcrumb?: ReactNode;
+    showPageControls?: boolean;
+    onPagePrev?: () => void;
+    onPageNext?: () => void;
+    /** Drawn at the ring's center, beneath the pills — usually a JimboMascot. */
+    center?: ReactNode;
+    className?: string;
+    "aria-label"?: string;
 }
-/** Badges arranged on a circle around a center point (mascot radial menu). */
-export declare function JimboOrbitalMenu({ items, onAction, radius, className, ...rest }: JimboOrbitalMenuProps): import("react").JSX.Element | null;
+/**
+ * Orbital radial menu.
+ *
+ * The south item stays pinned under the mascot; everyone else sits at equal
+ * angle steps with a single outward push when a pill would overlap the center.
+ * See ./orbitalLayout for why there is no iterative solver — the evenness is
+ * the whole effect.
+ */
+export declare function JimboOrbitalMenu({ items, onAction, onNavigate, onBack, currentMenu, closing, mascotSize, radius, radiusY, boxHeight, translateY, breadcrumb, showPageControls, onPagePrev, onPageNext, center, className, "aria-label": ariaLabel, }: JimboOrbitalMenuProps): import("react").JSX.Element | null;

package/dist/ui/JimboPanelSpinner.d.ts

@@ -0,0 +1,14 @@
+import { ReactNode } from 'react';
+export interface JimboPanelSpinnerProps {
+    label?: string;
+    title: string;
+    description?: string;
+    media?: ReactNode;
+    onPrev?: () => void;
+    onNext?: () => void;
+    canPrev?: boolean;
+    canNext?: boolean;
+    className?: string;
+}
+/** Fat Balatro option cycler: 140px arrows flanking a fixed-height face. */
+export declare function JimboPanelSpinner({ label, title, description, media, onPrev, onNext, canPrev, canNext, className, }: JimboPanelSpinnerProps): import("react").JSX.Element;

package/dist/ui/JimboPicker.d.ts

@@ -7,7 +7,7 @@ export interface JimboPickerGridProps extends HTMLAttributes<HTMLDivElement> {
     legendary?: boolean;
     scroll?: boolean;
 }
-export declare function JimboPickerGrid({ legendary, scroll: _scroll, className, children, ...rest }: JimboPickerGridProps): import("react").JSX.Element;
+export declare function JimboPickerGrid({ legendary, className, children, ...rest }: JimboPickerGridProps): import("react").JSX.Element;
 export interface JimboPickerItemProps extends HTMLAttributes<HTMLButtonElement> {
     muted?: boolean;
     title?: string;

package/dist/ui/JimboSeedCopyChip.d.ts

@@ -10,7 +10,6 @@ export interface JimboSeedCopyChipProps {
     style?: React.CSSProperties;
 }
 /**
- * Harvested from WeeJoker SeedCard — tap-to-copy seed row with icon + value.
- * Idle: copy icon + seed. Copied: green check + brief confirmation label.
+ * Tap-to-copy seed row. Idle: copy icon + seed. Copied: green check + label.
  */
 export declare function JimboSeedCopyChip({ value, placeholder, disabled, copiedLabel, copiedDurationMs, onCopy, className, style, }: JimboSeedCopyChipProps): React.JSX.Element;

package/dist/ui/JimboShopBelt.d.ts

@@ -0,0 +1,9 @@
+import { ReactNode } from 'react';
+export interface JimboShopBeltProps {
+    children?: ReactNode;
+    className?: string;
+    onNearEnd?: () => void;
+    snap?: boolean;
+}
+/** Horizontal pixel-card tape. Drag follows the finger; wheel maps to x. */
+export declare function JimboShopBelt({ children, className, onNearEnd, snap }: JimboShopBeltProps): import("react").JSX.Element;

package/dist/ui/dockTree.d.ts

@@ -0,0 +1,31 @@
+/** Dock tree — layout is user data. Harvested from seedfinder.app SeedLab dock.js. */
+export type DockDir = "row" | "column";
+export type DockEdge = "left" | "right" | "top" | "bottom" | "center";
+export interface DockGroup {
+    type: "group";
+    id: string;
+    panes: string[];
+    active: string | null;
+}
+export interface DockSplit {
+    type: "split";
+    id: string;
+    dir: DockDir;
+    ratio: number;
+    children: [DockNode, DockNode];
+}
+export type DockNode = DockGroup | DockSplit;
+export declare function defaultPyramidDock(keys: {
+    filter: string;
+    search: string;
+    results: string;
+    jamlyze: string;
+}): DockNode;
+export declare function dockRemove(node: DockNode, key: string): DockNode;
+export declare function dockMapGroup(node: DockNode, id: string, fn: (g: DockGroup) => DockGroup): DockNode;
+export declare function dockSplitAt(node: DockNode, id: string, key: string, side: DockEdge): DockNode;
+export declare function dockGroups(node: DockNode, acc?: DockGroup[]): DockGroup[];
+export declare function dockActivate(node: DockNode, key: string): DockNode;
+export declare function dockIsValid(node: DockNode, paneKeys: string[]): boolean;
+export declare function loadDock(storageKey: string, fallback: DockNode, paneKeys: string[]): DockNode;
+export declare function saveDock(storageKey: string, tree: DockNode): void;

package/dist/ui/hooks.d.ts

@@ -115,7 +115,7 @@ export declare function useJamlIdeDrag(filter: JamlVisualFilter, onChange: (filt
  * Provides a magnetic 3D tilt effect for DOM elements, replicating the hover-follow
  * of Balatro cards. Continuous (tracks the cursor). Pure CSS transform — no 3D deps.
  */
-export declare function useDOMMagneticTilt(enabled?: boolean): {
+export declare function useDOMMagneticTilt(enabledProp?: boolean): {
     handlers: {
         onPointerEnter: ((event: React.PointerEvent) => void) | undefined;
         onPointerLeave: (() => void) | undefined;