@hearthscale/app-ui 0.2.4 → 0.3.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ButtonHTMLAttributes, ReactNode, MouseEvent, CSSProperties, InputHTMLAttributes, RefObject, FocusEvent, Key, Ref } from 'react';
+import { ButtonHTMLAttributes, ReactNode, MouseEvent, CSSProperties, InputHTMLAttributes, FocusEvent, RefObject, Key, Ref } from 'react';
 
 type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger';
 type ButtonSize = 'sm' | 'md' | 'lg';
@@ -130,14 +130,15 @@ declare function StatusWord({ tone, live, children }: StatusWordProps): react.JS
 /**
  * A caption: the small label above a group, beside a value or under a
  * mark. It is set in the interface font, in sentence case; monospace is for
- * machine text only.
+ * code only.
  * @category Typography
  */
 declare function Label({ children }: {
     children: ReactNode;
 }): react.JSX.Element;
 /**
- * Machine text inside a sentence or a row: a key, an id, a hash, a path.
+ * Machine text inside a sentence or a row: a key, an id, a hash, a path,
+ * in the interface font with even digits.
  * @category Typography
  */
 declare function Mono({ children }: {
@@ -216,6 +217,94 @@ interface SegmentedControlProps<T extends string> {
  */
 declare function SegmentedControl<T extends string>({ value, options, onChange, label, disabled, }: SegmentedControlProps<T>): react.JSX.Element;
 
+interface MenuAnchor {
+    key: string;
+    element: HTMLElement;
+}
+/** Keeps the clicked element as the menu's positioning reference. */
+declare function anchorFrom(key: string, e: MouseEvent<HTMLElement>): MenuAnchor;
+/** A count of the theme's `--space` unit, the length a menu's sizes take so
+ *  that they follow the theme. @category Overlays */
+type SpaceLength = `calc(var(--space) * ${number})`;
+/** `n` units of the theme's `--space`. @category Overlays */
+declare const spaces: (n: number) => SpaceLength;
+/** The heavy-frost popup surface a context menu or picker sits on. It is
+ *  drawn into the popup root, so no scroll container clips it and no glass
+ *  surface it opens from keeps it from frosting what lies behind.
+ *  @category Overlays */
+declare function MenuSurface({ anchor, align, dir, minWidth, maxWidth, maxHeight, fit, keyboard, onDismiss, children, }: {
+    anchor: MenuAnchor;
+    align?: 'auto' | 'left' | 'right';
+    dir?: 'down' | 'up' | 'right';
+    /** The least width; the menu is never narrower than its anchor. */
+    minWidth?: SpaceLength;
+    /** The menu takes its anchor's width and corners exactly, as a picker
+     *  that opens beneath its own field does. */
+    fit?: boolean;
+    keyboard?: boolean;
+    /** Caps a menu whose rows carry prose, which would otherwise stretch to
+     *  the width of the longest sentence. */
+    maxWidth?: SpaceLength;
+    /** Caps a long list, which then scrolls, opened on its selected row. */
+    maxHeight?: SpaceLength;
+    onDismiss: () => void;
+    children: ReactNode;
+}): react.ReactPortal;
+/** One row of a shell menu: glyph, label, optional sub/chip/check. @category Overlays */
+declare function MItem({ icon, label, sub, chip, checked, selected, danger, disabled, onClick, trailing, }: {
+    icon?: ReactNode;
+    label: string;
+    sub?: string;
+    chip?: string;
+    checked?: boolean;
+    selected?: boolean;
+    danger?: boolean;
+    /** Drawn dimmed and inert: the row stays visible so the reason for it
+     *  being unavailable is readable beside it. */
+    disabled?: boolean;
+    onClick?: () => void;
+    /** What sits at the row's end: a switch, a chevron. */
+    trailing?: ReactNode;
+}): react.JSX.Element;
+/** A row that opens a flyout on the side with space while hovered. The
+ *  flyout closes as a menu does, with this row as its trigger, and a row
+ *  opens its flyout only while no other row of its menu holds one.
+ *  @category Overlays */
+declare function MSub({ icon, label, minWidth, children, }: {
+    icon?: ReactNode;
+    label: string;
+    /** The flyout's least width. */
+    minWidth?: SpaceLength;
+    children: ReactNode;
+}): react.JSX.Element;
+/** Hairline between menu groups. @category Overlays */
+declare function MDivider(): react.JSX.Element;
+/** Mono-caps section label inside a menu. @category Overlays */
+declare function MSection({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+/** Where a floating tip sits against its mark. */
+type TipPlacement = 'bottom-start' | 'bottom' | 'top' | 'right';
+interface TipMore {
+    sub?: string | undefined;
+    chip?: string | undefined;
+}
+/** Spread `hover` on the mark and render `tip` inside it. `show` and `hide` open
+ *  and close the tip with no pointer move, for words that arrive after a press.
+ *  @category Overlays */
+declare function useFloatingTips(placement?: TipPlacement): (key: string, text: string | undefined, more?: TipMore) => {
+    show: (anchor: HTMLElement) => void;
+    hide: () => void;
+    hover: {
+        onMouseEnter: (e: MouseEvent<HTMLElement>) => void;
+        onFocus: (e: FocusEvent<HTMLElement>) => void;
+        onBlur: () => void;
+        onMouseLeave: () => void;
+        onMouseDown: () => void;
+    };
+    tip: react.JSX.Element | null;
+};
+
 /** One settings group, with a single border around its rows. @category Settings */
 declare function SettingsCard({ children }: {
     children: ReactNode;
@@ -228,14 +317,15 @@ declare function SettingsSection({ children, first, action, }: {
 }): react.JSX.Element;
 /** The settings surface's search field: the shell's address-field recipe,
  *  whose placeholder sits centred and slides left on focus. @category Settings */
-declare function SettingsSearch({ value, placeholder, onChange, }: {
+declare function SettingsSearch({ value, placeholder, onChange, autoFocus, }: {
     value: string;
     placeholder: string;
     onChange: (value: string) => void;
+    autoFocus?: boolean;
 }): react.JSX.Element;
 /** A picker on the shell's own menu, in place of a native select.
  *  @category Settings */
-declare function SettingsSelect<T extends string>({ value, options, onPick, minWidth, menuHeight, menuWidth, placeholder, disabled, label, }: {
+declare function SettingsSelect<T extends string>({ value, options, onPick, minWidth, menuHeight, menuWidth, placeholder, disabled, label, note, }: {
     value: T;
     /** `disabled` keeps an entry visible and inert, so the reason it cannot
      *  be picked is readable where the pick is made. */
@@ -247,23 +337,30 @@ declare function SettingsSelect<T extends string>({ value, options, onPick, minW
         disabled?: boolean;
     }[];
     onPick: (value: T) => void;
-    minWidth?: number;
+    /** The menu's least width. */
+    minWidth?: SpaceLength;
     /** Caps the menu of a long list, which then scrolls. */
-    menuHeight?: number;
+    menuHeight?: SpaceLength;
     /** Caps the menu of rows whose sub lines carry prose, which then wraps. */
-    menuWidth?: number;
+    menuWidth?: SpaceLength;
     placeholder?: string;
     disabled?: boolean;
     label?: string;
+    /** Quiet words at the button's end, which give way before the row grows. */
+    note?: string | undefined;
 }): react.JSX.Element;
 /** A labelled row with a toggle at its end. @category Settings */
-declare function ToggleRow({ id, title, sub, help, on, onFlip, }: {
+declare function ToggleRow({ id, mark, title, sub, help, actions, on, onFlip, }: {
     id?: string;
+    /** What stands at the start of the row, such as a model's logo. */
+    mark?: ReactNode;
     title: string;
     /** Only where the label cannot carry the meaning on its own. */
     sub?: string;
     /** An explanation behind a question mark, for the same case. */
     help?: string;
+    /** Presses on what the switch governs, beside it. */
+    actions?: ReactNode;
     on: boolean;
     onFlip?: () => void;
 }): react.JSX.Element;
@@ -325,82 +422,46 @@ declare function SettingsTabs<T extends string>({ label, value, tabs, onPick, pa
     panelRef?: RefObject<HTMLElement | null>;
 }): react.JSX.Element;
 
-interface MenuAnchor {
-    key: string;
-    element: HTMLElement;
-}
-/** Keeps the clicked element as the menu's positioning reference. */
-declare function anchorFrom(key: string, e: MouseEvent<HTMLElement>): MenuAnchor;
-/** The heavy-frost popup surface a context menu or picker sits on. It is
- *  drawn into the popup root, so no scroll container clips it and no glass
- *  surface it opens from keeps it from frosting what lies behind.
- *  @category Overlays */
-declare function MenuSurface({ anchor, align, dir, minWidth, maxWidth, maxHeight, fit, keyboard, onDismiss, children, }: {
-    anchor: MenuAnchor;
-    align?: 'auto' | 'left' | 'right';
-    dir?: 'down' | 'up' | 'right';
-    minWidth?: number;
-    /** The menu takes its anchor's width and corners exactly, as a picker
-     *  that opens beneath its own field does. */
-    fit?: boolean;
-    keyboard?: boolean;
-    /** Caps a menu whose rows carry prose, which would otherwise stretch to
-     *  the width of the longest sentence. */
-    maxWidth?: number;
-    /** Caps a long list, which then scrolls, opened on its selected row. */
-    maxHeight?: number;
-    onDismiss: () => void;
+interface ModalProps {
+    title: string;
     children: ReactNode;
-}): react.ReactPortal;
-/** One row of a shell menu: glyph, label, optional sub/chip/check. @category Overlays */
-declare function MItem({ icon, label, sub, chip, checked, selected, danger, disabled, onClick, trailing, }: {
-    icon?: ReactNode;
-    label: string;
-    sub?: string;
-    chip?: string;
-    checked?: boolean;
-    selected?: boolean;
-    danger?: boolean;
-    /** Drawn dimmed and inert: the row stays visible so the reason for it
-     *  being unavailable is readable beside it. */
-    disabled?: boolean;
-    onClick?: () => void;
-    /** What sits at the row's end: a switch, a chevron. */
-    trailing?: ReactNode;
-}): react.JSX.Element;
-/** A row that opens a flyout on the side with space while hovered. The
- *  flyout closes as a menu does, with this row as its trigger, and a row
- *  opens its flyout only while no other row of its menu holds one.
- *  @category Overlays */
-declare function MSub({ icon, label, minWidth, children, }: {
-    icon?: ReactNode;
+    onClose: () => void;
+    /** 460px is the settings dialog; widen only for genuinely wider content. */
+    width?: number;
+    /** Dims the page behind the card. A view in a modal draws with `false`, for
+     *  the host has dimmed its tile. */
+    scrim?: boolean;
+}
+/**
+ * The desktop dialog: a centred `--win` card over a dimmed page. The close
+ * press, Escape and a press outside the card close it.
+ * @category Overlays
+ */
+declare function Modal({ title, children, onClose, width, scrim }: ModalProps): react.JSX.Element;
+
+interface MultiSelectProps {
+    /** What the choice is of, as a person reads it: `Languages`. */
     label: string;
-    minWidth?: number;
-    children: ReactNode;
-}): react.JSX.Element;
-/** Hairline between menu groups. @category Overlays */
-declare function MDivider(): react.JSX.Element;
-/** Mono-caps section label inside a menu. @category Overlays */
-declare function MSection({ children }: {
-    children: ReactNode;
-}): react.JSX.Element;
-/** Where a floating tip sits against its mark. */
-type TipPlacement = 'bottom-start' | 'bottom' | 'top' | 'right';
-interface TipMore {
-    sub?: string | undefined;
-    chip?: string | undefined;
+    /** The values to offer, in their order. */
+    options: string[];
+    labelOf: (value: string) => string;
+    picked: string[];
+    onPick: (picked: string[]) => void;
+    searchWords: string;
+    /** The word of several values in the button: `languages`. */
+    countWord: string;
+    onOpen?: () => void;
+    align?: 'auto' | 'left' | 'right';
+    /** The words of having none chosen, which the menu then offers. Without them,
+     *  the last value stays chosen. */
+    all?: string;
 }
-/** Spread `hover` on the mark and render `tip` inside it. @category Overlays */
-declare function useFloatingTips(placement?: TipPlacement): (key: string, text: string | undefined, more?: TipMore) => {
-    hover: {
-        onMouseEnter: (e: MouseEvent<HTMLElement>) => void;
-        onFocus: (e: FocusEvent<HTMLElement>) => void;
-        onBlur: () => void;
-        onMouseLeave: () => void;
-        onMouseDown: () => void;
-    };
-    tip: react.JSX.Element | null;
-};
+/**
+ * A choice of several values: a select whose menu holds the shell's search field
+ * and a check beside each value it keeps open for the next one.
+ * @category Settings
+ */
+declare function MultiSelect({ label, options, labelOf, picked, onPick, searchWords, countWord, onOpen, align, all, }: MultiSelectProps): react.JSX.Element;
 
 interface ShellConfirmProps {
     title: string;
@@ -408,7 +469,7 @@ interface ShellConfirmProps {
     /** The action's label, in the imperative: "Regenerate", "Delete 3 sessions". */
     action: string;
     /** The action's look: `danger` where the action destroys something,
-     *  `primary` where it installs or buys. */
+     *  `primary` for any other action. */
     tone?: 'danger' | 'primary';
     /** The mark before the action's label. A `danger` action without one
      *  carries the delete mark. */
@@ -642,6 +703,12 @@ interface PersonMarkProps {
  */
 declare function PersonMark({ name, picture, size, swatch }: PersonMarkProps): react.JSX.Element;
 
+/**
+ * Control: the first-party half of the inference contract — everything the
+ * OpenAI shape cannot express. Served by the Server (`hearthd`) beside the
+ * generation routes.
+ */
+
 /** Resolved publisher identity, independent of the model architecture.
  *  `GET /v1/publishers/{owner}/picture` answers the picture of the Hub
  *  user or organisation `repository` names first: its bytes as
@@ -748,5 +815,5 @@ interface IconProps {
  */
 declare function Icon({ name, size, className, style }: IconProps): react.JSX.Element;
 
-export { Button, Card, Chip, DateGrid, DatePicker, EmptyState, FactRow, Icon, IconButton, InfoRow, Kbd, Label, Lightbox, LinkRow, ListRow, MDivider, MItem, MSection, MSub, MenuSurface, Meter, ModelAvatar, Mono, Notice, OverlayScroll, PageTitle, PersonMark, PictureCompare, Popover, PublisherPicturesContext, SWATCHES, SegmentedControl, SettingsCard, SettingsSearch, SettingsSection, SettingsSelect, SettingsTabs, ShellConfirm, Slider, StatusWord, SwatchPicker, TextField, TextInput, TimePicker, Toast, Toggle, ToggleRow, VirtualList, anchorFrom, useFloatingTips };
-export type { ButtonProps, ButtonSize, ButtonVariant, CardProps, ChipProps, ChipTone, ComparedPicture, DateGridProps, DatePickerProps, EmptyStateProps, IconButtonProps, IconButtonSize, IconName, IconProps, LightboxItem, LightboxProps, MenuAnchor, MeterProps, OverlayScrollProps, OwnIconName, PageTitleProps, PersonMarkProps, PictureCompareProps, PlainDate, PlainTime, PopoverPlacement, PopoverProps, PublisherPictures, SegmentedControlProps, ShellConfirmProps, SliderProps, StatusTone, StatusWordProps, Swatch, SwatchPickerProps, TextFieldProps, TextInputProps, TimePickerProps, ToastProps, ToggleProps, VirtualListHandle, VirtualListProps };
+export { Button, Card, Chip, DateGrid, DatePicker, EmptyState, FactRow, Icon, IconButton, InfoRow, Kbd, Label, Lightbox, LinkRow, ListRow, MDivider, MItem, MSection, MSub, MenuSurface, Meter, Modal, ModelAvatar, Mono, MultiSelect, Notice, OverlayScroll, PageTitle, PersonMark, PictureCompare, Popover, PublisherPicturesContext, SWATCHES, SegmentedControl, SettingsCard, SettingsSearch, SettingsSection, SettingsSelect, SettingsTabs, ShellConfirm, Slider, StatusWord, SwatchPicker, TextField, TextInput, TimePicker, Toast, Toggle, ToggleRow, VirtualList, anchorFrom, spaces, useFloatingTips };
+export type { ButtonProps, ButtonSize, ButtonVariant, CardProps, ChipProps, ChipTone, ComparedPicture, DateGridProps, DatePickerProps, EmptyStateProps, IconButtonProps, IconButtonSize, IconName, IconProps, LightboxItem, LightboxProps, MenuAnchor, MeterProps, ModalProps, MultiSelectProps, OverlayScrollProps, OwnIconName, PageTitleProps, PersonMarkProps, PictureCompareProps, PlainDate, PlainTime, PopoverPlacement, PopoverProps, PublisherPictures, SegmentedControlProps, ShellConfirmProps, SliderProps, SpaceLength, StatusTone, StatusWordProps, Swatch, SwatchPickerProps, TextFieldProps, TextInputProps, TimePickerProps, ToastProps, ToggleProps, VirtualListHandle, VirtualListProps };