@jfrader/ui 0.5.1 → 0.6.0

package/dist/types/components/stretch-refresh/stretch-refresh.d.ts

@@ -0,0 +1,49 @@
+import { type ComponentPropsWithRef, type ReactNode } from 'react';
+import { type Interpolation, type Theme } from '../../styling/css';
+import { type SxProps } from '../../styling/sx';
+import { type ButtonProps } from '../button';
+type Slot<E extends 'div' | 'header' | 'h2' | 'ul' | 'li'> = Omit<ComponentPropsWithRef<E>, 'children'> & {
+    css?: Interpolation<Theme>;
+};
+export interface StretchRefreshSlotProps<T> {
+    header?: Slot<'header'>;
+    title?: Slot<'h2'>;
+    subtitle?: Slot<'div'>;
+    feed?: Slot<'div'>;
+    list?: Slot<'ul'>;
+    item?: Slot<'li'> | ((item: T, index: number) => Slot<'li'>);
+    indicator?: Omit<Slot<'div'>, 'aria-hidden'>;
+    refreshButton?: Omit<ButtonProps, 'children' | 'type' | 'disabled' | 'loading' | 'render' | 'sx'>;
+    status?: Omit<Slot<'div'>, 'role' | 'aria-atomic'>;
+    empty?: Slot<'div'>;
+}
+export interface StretchRefreshLabels {
+    refresh?: string;
+    refreshing?: string;
+    pull?: string;
+    release?: string;
+    done?: string;
+    error?: string;
+}
+export interface StretchRefreshProps<T> extends Omit<ComponentPropsWithRef<'div'>, 'children' | 'title'>, SxProps {
+    title: ReactNode;
+    headingLevel?: 2 | 3 | 4 | 5 | 6;
+    subtitle?: ReactNode;
+    items: readonly T[];
+    getKey: (item: T) => string;
+    renderItem: (item: T, index: number) => ReactNode;
+    onRefresh: () => Promise<string | void>;
+    refreshing?: boolean;
+    defaultRefreshing?: boolean;
+    onRefreshingChange?: (refreshing: boolean) => void;
+    disabled?: boolean;
+    threshold?: number;
+    emptyContent?: ReactNode;
+    labels?: StretchRefreshLabels;
+    slotProps?: StretchRefreshSlotProps<T>;
+}
+export declare function StretchRefresh<T>({ title, headingLevel, subtitle, items, getKey, renderItem, onRefresh, refreshing, defaultRefreshing, onRefreshingChange, disabled, threshold: thresholdProp, emptyContent, labels, slotProps, ref, className, sx, onKeyDown, ...props }: StretchRefreshProps<T>): import("@emotion/react/jsx-runtime").JSX.Element;
+export declare namespace StretchRefresh {
+    var displayName: string;
+}
+export {};

package/dist/types/components/theme-root/index.d.ts

@@ -1,2 +1,3 @@
 export { ThemeRoot } from './theme-root';
 export type { ThemeName, ThemeRootProps } from './theme-root';
+export { createTheme, themeTokenStyle, type CreateThemeOptions, type ThemeTokens } from '../../styling/create-theme';

package/dist/types/components/theme-root/theme-root.d.ts

@@ -1,9 +1,17 @@
 import { type ComponentPropsWithRef, type ReactNode } from 'react';
+import { type ThemeTokens } from '../../styling/create-theme';
 import { type SxProps } from '../../styling/sx';
 import { type ThemeName } from '../../styling/theme-scope';
 export type { ThemeName };
 export interface ThemeRootProps extends ComponentPropsWithRef<'div'>, SxProps {
+    /** The named palette the scope wears; `tokens` are declared over it. */
     theme?: ThemeName;
+    /**
+     * Token overrides for this scope (`createTheme()` builds them from an accent), declared as inline
+     * custom properties on the root. Omitted: a root naming the enclosing root's theme keeps that
+     * root's tokens; a root naming another theme drops them.
+     */
+    tokens?: ThemeTokens;
     /**
      * Where overlays inside this root portal to. Omitted: the enclosing ThemeRoot's container, else
      * the default (`body`). `null`: overlays wait until the host element is set.
@@ -11,7 +19,7 @@ export interface ThemeRootProps extends ComponentPropsWithRef<'div'>, SxProps {
     portalContainer?: HTMLElement | null;
     children?: ReactNode;
 }
-export declare function ThemeRoot({ ref, theme, portalContainer, className, sx, ...rest }: ThemeRootProps): import("@emotion/react/jsx-runtime").JSX.Element;
+export declare function ThemeRoot({ ref, theme, tokens, portalContainer, className, style, sx, ...rest }: ThemeRootProps): import("@emotion/react/jsx-runtime").JSX.Element;
 export declare namespace ThemeRoot {
     var displayName: string;
 }

package/dist/types/components/{comment-thread → thread}/thread-parts.d.ts

@@ -71,12 +71,14 @@ export interface ThreadReactionsProps {
     onToggle: (emoji: string) => void;
     pickerId: string;
     part?: ThreadPartProps;
+    overlay?: boolean;
+    counts?: ReadonlyMap<string, number>;
 }
 /**
  * Picker keyboard: Left/Right (mirrored in RTL) wrap across the emoji, Home/End jump; Escape and
  * a chosen emoji close it and return focus to the add button. Pressing outside leaves it open.
  */
-export declare function ThreadReactions({ ui: owner, reactions, offered, currentUserId, formatters, labels, readOnly, disabled, pickerOpen, onPickerOpenChange, onToggle, pickerId, part, }: ThreadReactionsProps): import("@emotion/react/jsx-runtime").JSX.Element | null;
+export declare function ThreadReactions({ ui: owner, reactions, offered, currentUserId, formatters, labels, readOnly, disabled, pickerOpen, onPickerOpenChange, onToggle, pickerId, part, overlay, counts, }: ThreadReactionsProps): import("@emotion/react/jsx-runtime").JSX.Element | null;
 export interface ThreadComposerProps {
     ui: string;
     draft: string;
@@ -108,7 +110,10 @@ export interface ThreadComposerProps {
     part?: ThreadPartProps;
     /** Distinguishes composers inside one thread (`data-composer`). */
     kind: string;
+    submitOnEnter?: boolean;
+    allowEmpty?: boolean;
+    lockWhilePending?: boolean;
 }
 /** Per-size layout variables read by the parts; the owning root applies them. */
 export declare const threadSizeStyles: Record<ThreadSize, SerializedStyles>;
-export declare function ThreadComposer({ ui: owner, draft, onDraftChange, onSubmit, onCancel, cancelOnEscape, cancelable, label, placeholder, submitLabel, cancelLabel, mentionsLabel, people, locale, disabled, pending, autoFocus, size, author, textareaProps, submitProps, part, kind, }: ThreadComposerProps): import("@emotion/react/jsx-runtime").JSX.Element;
+export declare function ThreadComposer({ ui: owner, draft, onDraftChange, onSubmit, onCancel, cancelOnEscape, cancelable, label, placeholder, submitLabel, cancelLabel, mentionsLabel, people, locale, disabled, pending, autoFocus, size, author, textareaProps, submitProps, part, kind, submitOnEnter, allowEmpty, lockWhilePending, }: ThreadComposerProps): import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/types/components/tooltip/tooltip.d.ts

@@ -1,5 +1,5 @@
 import { type ComponentPropsWithRef, type ReactNode } from 'react';
-import { type Placement } from '@floating-ui/react';
+import { type FloatingRootContext, type Placement, type UseInteractionsReturn } from '@floating-ui/react';
 import { type SxProps } from '../../styling/sx';
 export interface TooltipProps {
     open?: boolean;
@@ -16,6 +16,13 @@ export interface TooltipTriggerProps extends ComponentPropsWithRef<'button'>, Sx
 }
 export interface TooltipContentProps extends ComponentPropsWithRef<'div'>, SxProps {
 }
+export declare const tooltipContentStyle: import("@emotion/react").SerializedStyles;
+/** The tooltip interaction chain, shared with parts whose operative element cannot be a Tooltip.Trigger. */
+export declare function useTooltipInteractions(context: FloatingRootContext, { enabled, openDelay, closeDelay, }?: {
+    enabled?: boolean;
+    openDelay?: number;
+    closeDelay?: number;
+}): UseInteractionsReturn;
 declare function TooltipRoot(props: TooltipProps): import("@emotion/react/jsx-runtime").JSX.Element;
 declare function TooltipTrigger({ ref, 'aria-describedby': ariaDescribedByProp, className, sx, ...rest }: TooltipTriggerProps): import("@emotion/react/jsx-runtime").JSX.Element;
 declare function TooltipContent(props: TooltipContentProps): import("@emotion/react/jsx-runtime").JSX.Element | null;

package/dist/types/components/usage-meter/usage-meter.d.ts

@@ -1,7 +1,8 @@
 import { type ComponentPropsWithRef, type ComponentPropsWithoutRef, type ReactNode } from 'react';
 import { type Interpolation, type Theme } from '../../styling/css';
 import { type SxProps } from '../../styling/sx';
-export type UsageMeterState = 'normal' | 'near-limit' | 'over-limit' | 'unavailable';
+import { type UsageMeterState, type UsageMeterSummary } from './usage-model';
+export type { UsageMeterState, UsageMeterSummary } from './usage-model';
 export type UsageMeterSize = 'sm' | 'md' | 'lg';
 export type UsageMeterSelection = {
     kind: 'segment';
@@ -20,17 +21,6 @@ export type UsageMeterItem = UsageMeterSelection & {
     label: string;
     value: number;
 };
-export interface UsageMeterSummary {
-    total: number;
-    limit: number;
-    free: number;
-    over: number;
-    ratio: number;
-    state: UsageMeterState;
-    formattedTotal: string;
-    formattedLimit: string;
-    formattedPercent: string;
-}
 export interface UsageMeterLabels {
     free: string;
     near: string;

package/dist/types/components/usage-meter/usage-model.d.ts

@@ -0,0 +1,30 @@
+export type UsageMeterState = 'normal' | 'near-limit' | 'over-limit' | 'unavailable';
+export interface UsageMeterSummary {
+    total: number;
+    limit: number;
+    free: number;
+    over: number;
+    ratio: number;
+    state: UsageMeterState;
+    formattedTotal: string;
+    formattedLimit: string;
+    formattedPercent: string;
+}
+export declare const DEFAULT_WARN_AT = 0.9;
+export interface UsageFormats {
+    amount: Intl.NumberFormat;
+    percent: Intl.NumberFormat;
+    index: Intl.NumberFormat;
+}
+export declare function createUsageFormats(locale: Intl.LocalesArgument, numberFormatOptions?: Intl.NumberFormatOptions): UsageFormats;
+interface SummarizeOptions {
+    warnAt?: number;
+    formats: UsageFormats;
+    /** Text for amounts that cannot be computed. */
+    unavailable: string;
+    /** Formats amounts instead of `formats.amount` (consumer unit formatters). */
+    formatAmount?: (amount: number) => string;
+}
+/** Summarizes `total` against `limit`; nonpositive or nonfinite limits are `unavailable`. */
+export declare function summarizeUsage(total: number, limit: number, { warnAt, formats, unavailable, formatAmount }: SummarizeOptions): UsageMeterSummary;
+export {};

package/dist/types/components/user-menu/index.d.ts

@@ -0,0 +1,2 @@
+export { UserMenu } from './user-menu';
+export type { UserMenuContentProps, UserMenuGroupSlotProps, UserMenuIdentityProps, UserMenuItemProps, UserMenuItemTone, UserMenuPartProps, UserMenuProps, UserMenuSeparatorProps, UserMenuSignOutProps, UserMenuStatus, UserMenuStatusGroupProps, UserMenuTheme, UserMenuThemeGroupProps, UserMenuTriggerProps, UserMenuUser, UserMenuVariant, } from './user-menu';

package/dist/types/components/user-menu/user-menu.d.ts

@@ -0,0 +1,119 @@
+import { type ComponentPropsWithRef, type ReactNode } from 'react';
+import { type Placement } from '@floating-ui/react';
+import { type Interpolation, type Theme } from '../../styling/css';
+import { type SxProps } from '../../styling/sx';
+import { type AvatarStatus } from '../avatar';
+import { type MenuItemTone } from '../menu/menu';
+declare const THEME_OPTIONS: readonly ['light', 'dark', 'system'];
+declare const STATUS_OPTIONS: readonly ['available', 'busy', 'away'];
+export type UserMenuTheme = (typeof THEME_OPTIONS)[number];
+export type UserMenuStatus = (typeof STATUS_OPTIONS)[number];
+export type UserMenuVariant = 'adaptive' | 'menu' | 'sheet';
+export type UserMenuItemTone = MenuItemTone;
+export interface UserMenuUser {
+    name: string;
+    email: string;
+    /** Plan or role label shown next to the email; `0` renders. */
+    plan?: ReactNode;
+    avatarSrc?: string;
+}
+export interface UserMenuPartProps {
+    className?: string;
+    css?: Interpolation<Theme>;
+}
+export interface UserMenuProps {
+    user: UserMenuUser;
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** Desktop placement next to the Trigger; flips when there is no room. */
+    placement?: Placement;
+    /** Viewport width in px below which `variant="adaptive"` content becomes a sheet. */
+    compactBreakpoint?: number;
+    children?: ReactNode;
+}
+export interface UserMenuTriggerProps extends Omit<ComponentPropsWithRef<'button'>, 'children'>, SxProps {
+    /** Translated name of the button, e.g. "Account menu, Ada Lovelace". */
+    'aria-label': string;
+    /** Shows the user's name next to the avatar outside compact viewports. */
+    showName?: boolean;
+    status?: AvatarStatus;
+    /** Translated status word, exposed as the Trigger's description. */
+    statusLabel?: string;
+}
+interface UserMenuContentBaseProps extends ComponentPropsWithRef<'div'>, SxProps {
+    slotProps?: {
+        menu?: UserMenuPartProps;
+        handle?: UserMenuPartProps;
+        close?: UserMenuPartProps;
+    };
+}
+export type UserMenuContentProps = UserMenuContentBaseProps & ({
+    variant: 'menu';
+    closeLabel?: string;
+} | {
+    variant?: 'adaptive' | 'sheet';
+    /** Translated name of the sheet's Close button. */
+    closeLabel: string;
+});
+export interface UserMenuIdentityProps extends ComponentPropsWithRef<'div'>, SxProps {
+}
+export interface UserMenuItemProps extends Omit<ComponentPropsWithRef<'button'>, 'onSelect'>, SxProps {
+    /** Called once when the item is activated. The menu then closes unless a click handler called
+     * `event.preventDefault()`. */
+    onSelect?: () => void;
+    disabled?: boolean;
+    tone?: UserMenuItemTone;
+    /** Decorative icon before the label. */
+    icon?: ReactNode;
+    /** Shortcut hint keys, shown as decoration only; no shortcut is registered. */
+    keys?: readonly string[];
+}
+export interface UserMenuGroupSlotProps {
+    label?: UserMenuPartProps;
+    option?: UserMenuPartProps;
+}
+interface ChoiceGroupProps<V extends string> extends Omit<ComponentPropsWithRef<'div'>, 'defaultValue'>, SxProps {
+    value?: V;
+    defaultValue?: V;
+    onValueChange?: (value: V) => void;
+    /** Translated group name and option labels. */
+    labels: {
+        group: string;
+    } & Record<V, string>;
+    slotProps?: UserMenuGroupSlotProps;
+}
+export type UserMenuThemeGroupProps = ChoiceGroupProps<UserMenuTheme>;
+export type UserMenuStatusGroupProps = ChoiceGroupProps<UserMenuStatus>;
+export interface UserMenuSignOutProps extends Omit<UserMenuItemProps, 'onSelect' | 'disabled'> {
+    /** Signs the user out. A returned promise keeps the item busy until it settles. */
+    onSignOut: () => void | PromiseLike<unknown>;
+    /** Translated label shown while the action is pending. */
+    pendingLabel: string;
+    /** Translated message announced when the action fails. */
+    errorMessage: string;
+    /** Receives the failure (a rejection or a synchronous throw). */
+    onSignOutError?: (error: unknown) => void;
+}
+export interface UserMenuSeparatorProps extends ComponentPropsWithRef<'div'>, SxProps {
+}
+declare function UserMenuRoot({ user, open, defaultOpen, onOpenChange, placement, compactBreakpoint, children, }: UserMenuProps): import("@emotion/react/jsx-runtime").JSX.Element;
+declare function UserMenuTrigger({ ref, showName, status, statusLabel, 'aria-describedby': ariaDescribedBy, className, sx, ...rest }: UserMenuTriggerProps): import("@emotion/react/jsx-runtime").JSX.Element;
+declare function UserMenuContent({ variant, id, ...props }: UserMenuContentProps): import("@emotion/react/jsx-runtime").JSX.Element | null;
+declare function UserMenuIdentity({ ref, className, sx, ...rest }: UserMenuIdentityProps): import("react").ReactPortal | null;
+declare function UserMenuItem({ tone, icon, keys, children, ...props }: UserMenuItemProps): import("@emotion/react/jsx-runtime").JSX.Element;
+declare function UserMenuThemeGroup(props: UserMenuThemeGroupProps): import("@emotion/react/jsx-runtime").JSX.Element;
+declare function UserMenuStatusGroup(props: UserMenuStatusGroupProps): import("@emotion/react/jsx-runtime").JSX.Element;
+declare function UserMenuSignOut({ onSignOut, pendingLabel, errorMessage, onSignOutError, tone, icon, keys, children, ...props }: UserMenuSignOutProps): import("@emotion/react/jsx-runtime").JSX.Element;
+declare function UserMenuSeparator(props: UserMenuSeparatorProps): import("@emotion/react/jsx-runtime").JSX.Element;
+export declare const UserMenu: typeof UserMenuRoot & {
+    Trigger: typeof UserMenuTrigger;
+    Content: typeof UserMenuContent;
+    Identity: typeof UserMenuIdentity;
+    Item: typeof UserMenuItem;
+    ThemeGroup: typeof UserMenuThemeGroup;
+    StatusGroup: typeof UserMenuStatusGroup;
+    SignOut: typeof UserMenuSignOut;
+    Separator: typeof UserMenuSeparator;
+};
+export {};

package/dist/types/index.d.ts

@@ -1,15 +1,19 @@
 export * from './components/accordion';
+export * from './components/activity-rings';
 export * from './components/alert';
 export * from './components/announcement-bar';
 export * from './components/avatar';
 export * from './components/avatar-group';
 export * from './components/badge';
+export * from './components/billing-toggle';
 export * from './components/bottom-sheet';
 export * from './components/breadcrumbs';
 export * from './components/button';
+export * from './components/button-group';
 export * from './components/calendar';
 export * from './components/card';
 export * from './components/carousel';
+export * from './components/chat-thread';
 export * from './components/checkbox';
 export * from './components/chip-group';
 export * from './components/code-block';
@@ -25,7 +29,6 @@ export * from './components/date-range-picker';
 export * from './components/dialog';
 export * from './components/divider';
 export * from './components/drawer';
-export * from './components/elastic-slider';
 export * from './components/empty-state';
 export * from './components/expandable-card';
 export * from './components/expanding-search';
@@ -38,13 +41,19 @@ export * from './components/inline-edit';
 export * from './components/hover-card';
 export * from './components/json-viewer';
 export * from './components/kbd';
+export * from './components/keycap-keyboard';
+export * from './components/lightbox-gallery';
+export * from './components/link-unfurl';
+export * from './components/locale-switcher';
 export * from './components/mention-input';
 export * from './components/menu';
 export * from './components/metric-card';
 export * from './components/multi-select';
 export * from './components/navigation';
+export * from './components/now-playing';
 export * from './components/pagination';
 export * from './components/password-field';
+export * from './components/photo-grid';
 export * from './components/pill';
 export * from './components/popover';
 export * from './components/progress';
@@ -55,6 +64,8 @@ export * from './components/scroll-area';
 export * from './components/search-field';
 export * from './components/segmented-control';
 export * from './components/select';
+export * from './components/sheet-stack';
+export * from './components/shortcut-recorder';
 export * from './components/signature-pad';
 export * from './components/skeleton';
 export * from './components/slider';
@@ -63,6 +74,7 @@ export * from './components/spinner';
 export * from './components/split-button';
 export * from './components/stack';
 export * from './components/stepper';
+export * from './components/stretch-refresh';
 export * from './components/swipe-actions';
 export * from './components/switch';
 export * from './components/tabs';
@@ -80,6 +92,7 @@ export * from './components/toggle-group';
 export * from './components/tooltip';
 export * from './components/tree-view';
 export * from './components/usage-meter';
+export * from './components/user-menu';
 export { styled } from './styling/styled';
 export type { SxProps } from './styling/sx';
 export { theme, type JfraderTheme } from './styling/theme';

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

@@ -0,0 +1,24 @@
+import type { NativeDialogTransition } from './use-native-dialog';
+/**
+ * Settles once the finite animations and transitions running on `element` (and, with `subtree`,
+ * its descendants and pseudo-elements such as `::backdrop`) have finished or been canceled.
+ * Infinite animations (spinners) never hold the exit.
+ */
+export declare function exitMotionFinished(element: Element, { subtree }?: {
+    subtree?: boolean | undefined;
+}): Promise<unknown>;
+/**
+ * Native dialog transition for styled motion: `useNativeDialog` renders `data-state="closing"`
+ * before the exit runs, so the exit only waits for the transitions that state started.
+ */
+export declare const styledDialogTransition: NativeDialogTransition;
+/**
+ * Presence for a floating surface that unmounts when closed: it stays mounted while `closing`
+ * so its exit transition (styled through `data-state="closing"`) can run. Attach `ref` to the
+ * surface; reopening during the exit keeps the same mount.
+ */
+export declare function useExitPresence<T extends Element>(open: boolean): {
+    ref: import("react").RefObject<T | null>;
+    present: boolean;
+    closing: boolean;
+};

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