@jfrader/ui 0.5.0 → 0.6.0

package/dist/types/overlay/overlay-layer.d.ts

@@ -21,6 +21,26 @@ export declare function OverlayLayer({ children }: {
 export declare namespace OverlayLayer {
     var displayName: string;
 }
+/**
+ * A layer for a menu. Its node joins the tree under the enclosing layer like any other, but the
+ * menu's own hooks see no parent node: useRole and useListNavigation read a parent node as a parent
+ * menu (a menuitem trigger, cross-axis open/close keys). The menu's content re-provides the node
+ * through `LayerContent`, so layers opened inside it nest under it.
+ */
+export declare function MenuLayer({ children }: {
+    children: (nodeId: string | undefined) => ReactNode;
+}): import("@emotion/react/jsx-runtime").JSX.Element;
+export declare namespace MenuLayer {
+    var displayName: string;
+}
+/** Makes `nodeId` the parent of layers rendered inside `children`. */
+export declare function LayerContent({ nodeId, children }: {
+    nodeId: string | undefined;
+    children: ReactNode;
+}): import("@emotion/react/jsx-runtime").JSX.Element;
+export declare namespace LayerContent {
+    var displayName: string;
+}
 /**
  * Root boundary for an overlay that does not take part in layer nesting. Inside a layer it gets
  * its own empty tree and no parent node, so it never reads the enclosing layer as its parent.

package/dist/types/overlay/presence-spring.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Entrance and exit of a modal surface (Drawer, BottomSheet): critically damped, so it never
+ * overshoots, and at rest once within a pixel and slow, so a retained exit releases the modal promptly.
+ */
+export declare const PRESENCE_SPRING: {
+    readonly type: 'spring';
+    readonly stiffness: 900;
+    readonly damping: 60;
+    readonly mass: 1;
+    readonly restDelta: 1;
+    readonly restSpeed: 30;
+};

package/dist/types/overlay/use-native-dialog.d.ts

@@ -12,6 +12,14 @@ export interface NativeDialogHandlers {
     onClick?: MouseEventHandler<HTMLDialogElement>;
     onClose?: ReactEventHandler<HTMLDialogElement>;
 }
+/** Surface motion around the native lifecycle. */
+export interface NativeDialogTransition {
+    /** Runs after showModal() succeeds, and when a reopen interrupts a running exit. */
+    enter: (dialog: HTMLDialogElement) => void;
+    /** Runs on a logical close; the native close waits for the promise. Return nothing to close at once. */
+    exit: (dialog: HTMLDialogElement) => Promise<unknown> | undefined;
+}
+export type NativeDialogState = 'open' | 'closing' | 'closed';
 export declare function requestNativeDialogClose(dialog: HTMLDialogElement | null, setOpen: (open: boolean) => void): void;
 /** Root half: logical open requests, the repair token and the registered dialog element. */
 export declare function useNativeDialogRoot(open: boolean, requestOpenChange: (open: boolean) => void): {
@@ -31,9 +39,10 @@ export declare function omitNativeOpen<P extends object>(props: P & {
  * Content half: syncs the native dialog to the logical `open`, and returns the `ref` and
  * event handlers to spread on the <dialog> (after the consumer's props).
  */
-export declare function useNativeDialog({ open, setOpen, requestClose, repairToken, setDialogElement }: NativeDialogController, { onCancel, onClick, onClose }: NativeDialogHandlers, forwardedRef: Ref<HTMLDialogElement> | undefined, contentRef?: MutableRefObject<HTMLDialogElement | null>): {
+export declare function useNativeDialog({ open, setOpen, requestClose, repairToken, setDialogElement }: NativeDialogController, { onCancel, onClick, onClose }: NativeDialogHandlers, forwardedRef: Ref<HTMLDialogElement> | undefined, contentRef?: MutableRefObject<HTMLDialogElement | null>, transition?: NativeDialogTransition): {
     ref: (element: HTMLDialogElement | null) => void;
     onCancel: (event: SyntheticEvent<HTMLDialogElement>) => void;
     onClick: (event: MouseEvent<HTMLDialogElement>) => void;
     onClose: (event: SyntheticEvent<HTMLDialogElement>) => void;
+    'data-state': NativeDialogState;
 };

package/dist/types/overlay/use-overlay-floating.d.ts

@@ -1,4 +1,4 @@
-import { type OpenChangeReason, type Placement, type UseFloatingReturn } from '@floating-ui/react';
+import { type OpenChangeReason, type Placement, type Strategy, type UseFloatingReturn } from '@floating-ui/react';
 export interface OverlayFloatingOptions {
     open: boolean;
     onOpenChange: (open: boolean, event?: Event, reason?: OpenChangeReason) => void;
@@ -9,6 +9,13 @@ export interface OverlayFloatingOptions {
     boundary?: Element | null;
     /** Receives the space left for the surface inside the boundary after each positioning pass. */
     onAvailableSize?: (size: OverlayAvailableSize) => void;
+    /** CSS positioning strategy. Defaults to `absolute`. */
+    strategy?: Strategy;
+    /** Gap between the anchor and the surface, in px. Defaults to `ANCHOR_GAP`. */
+    gap?: number;
+    /** Position with `transform` (default) or with `left`/`top`, which leaves `transform` and
+     * `scale` free for the surface's own animation. */
+    transform?: boolean;
 }
 export interface OverlayAvailableSize {
     width: number;
@@ -18,4 +25,4 @@ export interface OverlayAvailableSize {
  * Shared positioning for Popover, Tooltip and Menu. `autoUpdate` only runs while both
  * elements are mounted, so a closed (unmounted) surface does no positioning work.
  */
-export declare function useOverlayFloating({ open, onOpenChange, placement, nodeId, boundary, onAvailableSize, }: OverlayFloatingOptions): UseFloatingReturn<HTMLButtonElement>;
+export declare function useOverlayFloating({ open, onOpenChange, placement, nodeId, boundary, onAvailableSize, strategy, gap, transform, }: OverlayFloatingOptions): UseFloatingReturn<HTMLButtonElement>;

package/dist/types/styling/create-theme.d.ts

@@ -0,0 +1,24 @@
+import type { CSSProperties } from 'react';
+import { type JfraderTheme } from './theme';
+import type { ThemeName } from './theme-scope';
+type TokenOverrides<T> = {
+    readonly [K in keyof T]?: T[K] extends string ? string : TokenOverrides<T[K]>;
+};
+/** Sparse token overrides for a ThemeRoot scope, typed from the palette: any path, any depth. */
+export type ThemeTokens = TokenOverrides<JfraderTheme>;
+export interface CreateThemeOptions {
+    /** The named theme the scope wears; picks the dark or light accent derivation. */
+    base?: ThemeName;
+    /** Accent fill as `#rgb` or `#rrggbb`; the accent family is derived from it. */
+    accent?: string;
+    /** Explicit overrides; they win over the derived accent family. */
+    tokens?: ThemeTokens;
+}
+/**
+ * A ThemeRoot `tokens` map: the named theme's palette, then the accent family derived for `base`,
+ * then `tokens` (explicit wins per token path). Pass the same `base` as the ThemeRoot's `theme`.
+ */
+export declare function createTheme({ base, accent, tokens }?: CreateThemeOptions): ThemeTokens;
+/** `tokens` as inline custom-property declarations, named after the generated `var()` references. */
+export declare function themeTokenStyle(tokens: ThemeTokens): CSSProperties;
+export {};

package/dist/types/styling/css.d.ts

@@ -1,3 +1,3 @@
-export { ClassNames, css, keyframes, ThemeProvider as EmotionThemeProvider, useTheme as useEmotionTheme, } from '@emotion/react';
+export { CacheProvider, ClassNames, css, keyframes, ThemeProvider as EmotionThemeProvider, useTheme as useEmotionTheme, } from '@emotion/react';
 export type { ClassNamesContent, Interpolation, SerializedStyles, Theme } from '@emotion/react';
 export type { JfraderTheme } from './theme';

package/dist/types/styling/overlay-motion.d.ts

@@ -0,0 +1,95 @@
+/** Scale a centered modal panel grows from. */
+export declare const MODAL_ENTER_SCALE = 0.96;
+/** A command palette comes in from a little further, for a quicker "summoned" feel. */
+export declare const PALETTE_ENTER_SCALE = 0.92;
+/** Timing of an entrance; exits are quicker. */
+export declare const enterTransition: {
+    readonly transitionDuration: "var(--ui-motion-duration-base)";
+    readonly transitionTimingFunction: "var(--ui-motion-ease-standard)";
+};
+export declare const exitTransition: {
+    readonly transitionDuration: "var(--ui-motion-duration-fast)";
+};
+/** Panel inside a native <dialog> rendered with `styledDialogTransition`. */
+export declare function modalPanelMotion(scale: number): {
+    readonly transitionDuration: "var(--ui-motion-duration-base)";
+    readonly transitionTimingFunction: "var(--ui-motion-ease-standard)";
+    readonly transitionProperty: 'opacity, scale, translate';
+    readonly '@starting-style': {
+        opacity: number;
+        scale: string;
+        translate: string;
+    };
+    readonly '[data-state="closing"] > &': {
+        readonly transitionDuration: "var(--ui-motion-duration-fast)";
+        readonly opacity: number;
+        readonly scale: string;
+        readonly translate: string;
+    };
+    readonly "@media (prefers-reduced-motion: reduce)": {
+        readonly '&, [data-state="closing"] > &': {
+            readonly transitionDuration: '0s';
+        };
+    };
+};
+/** The scrim of a native <dialog> fades with its panel. */
+export declare const modalBackdropMotion: {
+    readonly '&::backdrop': {
+        readonly transitionDuration: "var(--ui-motion-duration-base)";
+        readonly transitionTimingFunction: "var(--ui-motion-ease-standard)";
+        readonly transitionProperty: 'opacity';
+    };
+    readonly '&[open]::backdrop': {
+        readonly '@starting-style': {
+            readonly opacity: 0;
+        };
+    };
+    readonly '&[data-state="closing"]::backdrop': {
+        readonly transitionDuration: "var(--ui-motion-duration-fast)";
+        readonly opacity: 0;
+    };
+    readonly '&[data-state="closing"]': {
+        readonly pointerEvents: 'none';
+    };
+    readonly "@media (prefers-reduced-motion: reduce)": {
+        readonly '&::backdrop, &[data-state="closing"]::backdrop': {
+            readonly transitionDuration: '0s';
+        };
+    };
+};
+/**
+ * Floating surface that slides a little from its anchor: set `data-side` to the resolved side and
+ * `data-state="closing"` on the surface while it exits (see `useExitPresence`).
+ */
+export declare const floatingSurfaceMotion: {
+    readonly transitionDuration: "var(--ui-motion-duration-base)";
+    readonly transitionTimingFunction: "var(--ui-motion-ease-standard)";
+    readonly transitionProperty: 'opacity, translate';
+    readonly '@starting-style': {
+        readonly opacity: 0;
+        readonly translate: 'var(--overlay-enter-x, 0) var(--overlay-enter-y, 0)';
+    };
+    readonly '&[data-state="closing"]': {
+        readonly transitionDuration: "var(--ui-motion-duration-fast)";
+        readonly opacity: 0;
+        readonly translate: 'var(--overlay-enter-x, 0) var(--overlay-enter-y, 0)';
+        readonly pointerEvents: 'none';
+    };
+    readonly '&[data-side="bottom"]': {
+        readonly '--overlay-enter-y': "calc(-1 * var(--ui-space-1))";
+    };
+    readonly '&[data-side="top"]': {
+        readonly '--overlay-enter-y': "var(--ui-space-1)";
+    };
+    readonly '&[data-side="left"]': {
+        readonly '--overlay-enter-x': "var(--ui-space-1)";
+    };
+    readonly '&[data-side="right"]': {
+        readonly '--overlay-enter-x': "calc(-1 * var(--ui-space-1))";
+    };
+    readonly "@media (prefers-reduced-motion: reduce)": {
+        readonly '&, &[data-state="closing"]': {
+            readonly transitionDuration: '0s';
+        };
+    };
+};

package/dist/types/styling/surface.d.ts

@@ -1,3 +1,10 @@
+import type { ThemeName } from './theme-scope';
+/** Surface appearance: `contrast` wears the dark theme plus the elevated-charcoal overrides. */
+export type SurfaceAppearance = 'default' | 'contrast';
+/** The theme a surface appearance wears; `default` keeps whatever theme is in scope. */
+export declare function surfaceTheme(appearance: SurfaceAppearance): ThemeName | null;
+/** Attributes a surface sets for its appearance: the theme it wears and the overrides that go with it. */
+export declare function surfaceAttributes(appearance: SurfaceAppearance): Record<string, string> | null;
 /** Raised panel: surface color, hairline border and the base text setup. */
 export declare const raisedSurface: {
     readonly boxSizing: 'border-box';

package/dist/types/styling/theme-scope.d.ts

@@ -1,16 +1,42 @@
-import { type ReactNode } from 'react';
+import { type CSSProperties, type ReactNode } from 'react';
 export type ThemeName = 'dark' | 'light';
+/** Surface palette in scope: `contrast` adds the elevated-charcoal overrides on the dark theme. */
+export type AppearanceName = 'default' | 'contrast';
 export interface ThemeScope {
     theme: ThemeName;
+    appearance: AppearanceName;
     /** `undefined` keeps default portal routing; `null` holds portals until the host exists. */
     portalContainer: HTMLElement | null | undefined;
+    /** The scope root's `tokens` as inline custom properties, re-declared wherever `theme` is. */
+    tokenStyle: CSSProperties | undefined;
 }
 export declare const ThemeScopeContext: import("react").Context<ThemeScope | null>;
-/** The nearest ThemeRoot's scope, or `null` outside any ThemeRoot (page theme applies). */
+/** The nearest theme scope (ThemeRoot or contrast surface), or `null` outside any. */
 export declare function useThemeScope(): ThemeScope | null;
+/**
+ * The enclosing scope's `tokens` for an element that re-declares `theme`: kept when it names the
+ * same theme, dropped for another (they were derived for the enclosing one) or for `null`.
+ */
+export declare function carriedTokenStyle(parent: ThemeScope | null, theme: ThemeName | null): CSSProperties | undefined;
+/** Inline `style` for a scope element: carried tokens first, the consumer's own `style` last. */
+export declare function scopeStyle(tokenStyle: CSSProperties | undefined, style: CSSProperties | undefined): CSSProperties | undefined;
+/** `style` for a surface that re-declares `theme` (`null`: it re-declares nothing) inside the scope. */
+export declare function useSurfaceStyle(theme: ThemeName | null, style: CSSProperties | undefined): CSSProperties | undefined;
+/** The appearance a surface wears: its own value, else the enclosing scope's, else the theme's own. */
+export declare function useSurfaceAppearance(appearance?: AppearanceName): AppearanceName;
 /** What a `data-theme` scope root sets besides the attribute: inherited text color and color-scheme. */
 export declare const themeScopeStyle: import("@emotion/react").SerializedStyles;
-/** Re-applies the nearest ThemeRoot's theme around portaled content; renders children bare outside one. */
+/**
+ * Publishes a surface's theme and appearance to its subtree without taking over the enclosing
+ * `portalContainer`, so overlays opened inside a contrast surface keep its palette through their
+ * portal. `theme: null` keeps the enclosing theme; publishes only when the pair changes the scope.
+ */
+export declare function AppearanceScope({ theme, appearance, children, }: {
+    theme: ThemeName | null;
+    appearance: AppearanceName;
+    children?: ReactNode;
+}): string | number | bigint | boolean | import("@emotion/react/jsx-runtime").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | Iterable<ReactNode> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined> | null | undefined;
+/** Re-applies the nearest scope (theme, appearance and tokens) around portaled content. */
 export declare function ThemeBoundary({ children }: {
     children?: ReactNode;
 }): string | number | bigint | boolean | import("@emotion/react/jsx-runtime").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | Iterable<ReactNode> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined> | null | undefined;

package/dist/types/styling/theme.d.ts

@@ -102,6 +102,11 @@ export declare const theme: {
         };
         readonly easeStandard: "var(--ui-motion-ease-standard)";
     };
+    readonly size: {
+        readonly sheetStackBreakpoint: "var(--ui-size-sheet-stack-breakpoint)";
+        readonly sheetStackSheetPeek: "var(--ui-size-sheet-stack-sheet-peek)";
+        readonly sheetStackDialogPeek: "var(--ui-size-sheet-stack-dialog-peek)";
+    };
 };
 export type JfraderTheme = typeof theme;
 declare module '@emotion/react' {