panelui-web 0.3.0 → 0.5.0

package/dist/components/planet/index.js

@@ -47,7 +47,10 @@ import { tv } from 'tailwind-variants';
 import { LAND, LAND_COLUMNS, LAND_ROWS } from './land.js';
 const planetVariants = tv({
     slots: {
-        root: 'flex w-full flex-col items-center gap-4 text-foreground',
+        // `isolate` keeps the markers' depth ordering inside the planet. Each marker
+        // sets its own z-index, and without a stacking context of its own those
+        // numbers compete with the page's sidebars and menus, and win.
+        root: 'isolate flex w-full flex-col items-center gap-4 text-foreground',
         // `touch-pan-y` leaves a vertical swipe to the page. A globe that traps
         // the scroll it sits in is worse than one that only turns sideways.
         globe: 'relative aspect-square w-full max-w-md cursor-grab touch-pan-y select-none rounded-full outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-4 focus-visible:ring-offset-background active:cursor-grabbing',

package/dist/components/prompt/index.d.ts

@@ -0,0 +1,414 @@
+/**
+ * Prompt — where a message to an assistant is written, with what goes with
+ * it: files, a model, tools, and a button that sends it.
+ *
+ * ```tsx
+ * <Prompt onSubmit={({ text, files }) => send(text, files)} status={status} onStop={stop}>
+ *   <Prompt.Field>
+ *     <Prompt.Attachments />
+ *     <Prompt.Textarea placeholder="Ask anything" />
+ *     <Prompt.Footer>
+ *       <Prompt.Tools>
+ *         <Prompt.Menu>
+ *           <Prompt.AttachItem />
+ *         </Prompt.Menu>
+ *         <Prompt.Model items={models} defaultValue="swift" />
+ *       </Prompt.Tools>
+ *       <Prompt.Submit />
+ *     </Prompt.Footer>
+ *   </Prompt.Field>
+ *   <Prompt.Status>Reading the files</Prompt.Status>
+ * </Prompt>
+ * ```
+ *
+ * ## A field in a tray
+ *
+ * The field is a raised card. What is said about it, rather than in it, sits
+ * in bands that the card overlaps: `Prompt.Banner` above for something to do
+ * first, `Prompt.Status` below for what the answer is doing, and
+ * `Prompt.Context` below, inset, for where the message is going. A band opens
+ * and closes with its `open` prop, folding under the card, so a band can come
+ * and go without the page jumping by more than its own height.
+ *
+ * ## Sending
+ *
+ * Enter sends and Shift+Enter starts a new line; Enter while a character is
+ * still being composed is left to the input method. `onSubmit` is handed the
+ * text, trimmed, and the files, and the field is cleared. Nothing is sent
+ * while it is empty or while `status` is `submitted` or `streaming`.
+ *
+ * ## One button, four jobs
+ *
+ * `Prompt.Submit` sends. While the answer is on its way it stops it instead,
+ * calling `onStop`, with a ring turning round it. Given `onVoice`, it is a
+ * voice button while the field is empty, and its bars move while `listening`.
+ * The icons cross-fade in place, so the button never moves under the pointer.
+ *
+ * ## Files
+ *
+ * Files arrive from `Prompt.AttachItem` in the menu or `Prompt.Attach`, from
+ * ⌘U or Ctrl+U in the field, from a paste, or dropped on the field.
+ * `accept` and `maxFiles` decide which are taken, and `onReject` is told about
+ * the rest. Images are shown as thumbnails, anything else as a chip with its
+ * name and size.
+ */
+import { type ComponentProps, type ReactNode } from 'react';
+import { type ButtonProps } from '../button/index.js';
+import { type MenuContentProps, type MenuItemProps } from '../menu/index.js';
+import { type TextareaProps } from '../textarea/index.js';
+export type PromptState = 'idle' | 'submitted' | 'streaming' | 'error';
+export interface PromptMessage {
+    /** What was written, trimmed. */
+    text: string;
+    /** The files that were attached, in the order they were added. */
+    files: File[];
+}
+export interface PromptAttachment {
+    id: string;
+    file: File;
+    /** An object URL for an image, to show it by. */
+    preview?: string;
+}
+export type PromptRejectReason = 'accept' | 'max-files';
+export interface PromptProps extends Omit<ComponentProps<'form'>, 'onSubmit' | 'defaultValue'> {
+    /** What is written in the field, when the caller holds it. */
+    value?: string;
+    /** What the field starts with, when the caller does not hold it. */
+    defaultValue?: string;
+    /** Called with what is written, each time it changes, and with `''` when it is sent. */
+    onValueChange?: (value: string) => void;
+    /** Called with the text and the files when the message is sent. */
+    onSubmit?: (message: PromptMessage) => void;
+    /**
+     * Where the answer is. `submitted` and `streaming` stop the field being
+     * sent and turn the submit button into a stop button; `error` marks the
+     * field. Default `idle`.
+     */
+    status?: PromptState;
+    /** Called when the stop button is pressed. Without it, the button cannot be pressed while busy. */
+    onStop?: () => void;
+    /** Turns the whole prompt off. */
+    disabled?: boolean;
+    /** Files attached to begin with, such as those of a message being edited and sent again. */
+    defaultFiles?: File[];
+    /** Which files can be attached, as for `<input type="file">`: `image/*,.pdf`. Default any. */
+    accept?: string;
+    /** How many files can be attached at once. Default no limit. */
+    maxFiles?: number;
+    /** Called with the files that were not taken, and why. */
+    onReject?: (files: File[], reason: PromptRejectReason) => void;
+}
+declare function PromptRoot({ value: controlledValue, defaultValue, onValueChange, onSubmit, status, onStop, disabled, defaultFiles, accept, maxFiles, onReject, className, children, ...props }: PromptProps): import("react").JSX.Element;
+declare namespace PromptRoot {
+    var displayName: string;
+}
+export interface PromptBannerProps extends ComponentProps<'div'> {
+    /** Whether it is shown. It folds under the field when it is not. Default `true`. */
+    open?: boolean;
+}
+/** A band above the field, for something to do before or while writing: connect an account, pick a project. */
+declare function PromptBanner({ open, ...props }: PromptBannerProps): import("react").JSX.Element;
+declare namespace PromptBanner {
+    var displayName: string;
+}
+export interface PromptBannerActionProps extends ButtonProps {
+}
+/** The banner's button, at its end. */
+declare function PromptBannerAction({ className, size, shape, ...props }: PromptBannerActionProps): import("react").JSX.Element;
+declare namespace PromptBannerAction {
+    var displayName: string;
+}
+export interface PromptStatusProps extends ComponentProps<'div'> {
+    /** Whether it is shown. Default: while `status` is `submitted` or `streaming`. */
+    open?: boolean;
+    /** Something before the words: the model's mark, a tool's icon. */
+    icon?: ReactNode;
+    /** Whether a spinner turns at its end. Default `true`. */
+    spinner?: boolean;
+}
+/** A band under the field saying what the answer is doing, with the words lit by a moving sweep. */
+declare function PromptStatus({ open, icon, spinner, children, ...props }: PromptStatusProps): import("react").JSX.Element;
+declare namespace PromptStatus {
+    var displayName: string;
+}
+export interface PromptContextProps extends ComponentProps<'div'> {
+}
+/** A strip under the field, inset from its edges, for where the message is going: a branch, a folder, a ticket. */
+declare function PromptContext({ className, ...props }: PromptContextProps): import("react").JSX.Element;
+declare namespace PromptContext {
+    var displayName: string;
+}
+export interface PromptContextItemProps extends ComponentProps<'span'> {
+    /** Called when it is pressed. Passing this makes the item a button. */
+    onSelect?: () => void;
+}
+/** One fact in the context strip, with an icon before it. */
+declare function PromptContextItem({ onSelect, className, children, ...props }: PromptContextItemProps): import("react").JSX.Element;
+declare namespace PromptContextItem {
+    var displayName: string;
+}
+export interface PromptHintProps extends ComponentProps<'p'> {
+}
+/** A quiet line under the prompt. Keys written in `<kbd>` are drawn as keys. */
+declare function PromptHint({ className, children, ...props }: PromptHintProps): import("react").JSX.Element;
+declare namespace PromptHint {
+    var displayName: string;
+}
+export interface PromptFieldProps extends ComponentProps<'div'> {
+    /**
+     * `stacked` puts the text above a footer. `inline` puts every part in one
+     * row, the text between them, for a one-line composer; the row wraps as
+     * the text grows. Default `stacked`.
+     */
+    layout?: 'stacked' | 'inline';
+}
+/** The card that holds the text, the files and the footer. Files can be dropped on it. */
+declare function PromptField({ layout, className, onDragOver, onDragLeave, onDrop, ...props }: PromptFieldProps): import("react").JSX.Element;
+declare namespace PromptField {
+    var displayName: string;
+}
+export interface PromptTextareaProps extends Omit<TextareaProps, 'value' | 'defaultValue' | 'onChange' | 'variant'> {
+}
+/** Where the message is written. Enter sends, Shift+Enter starts a new line, and pasted files are attached. */
+declare function PromptTextarea({ className, minRows, maxRows, onKeyDown, onPaste, 'aria-label': ariaLabel, ...props }: PromptTextareaProps): import("react").JSX.Element;
+declare namespace PromptTextarea {
+    var displayName: string;
+}
+export interface PromptAttachmentsProps extends ComponentProps<'ul'> {
+}
+/** The files attached so far: images as thumbnails, anything else as a chip. Takes no room while there are none. */
+declare function PromptAttachments({ className, 'aria-label': ariaLabel, ...props }: PromptAttachmentsProps): import("react").JSX.Element | null;
+declare namespace PromptAttachments {
+    var displayName: string;
+}
+export interface PromptFooterProps extends ComponentProps<'div'> {
+}
+/** The row under the text: tools at the start, the submit button at the end. */
+declare function PromptFooter({ className, ...props }: PromptFooterProps): import("react").JSX.Element;
+declare namespace PromptFooter {
+    var displayName: string;
+}
+export interface PromptToolsProps extends ComponentProps<'div'> {
+}
+/** The tools at the start of the footer. Wraps onto a second line where it has to. */
+declare function PromptTools({ className, ...props }: PromptToolsProps): import("react").JSX.Element;
+declare namespace PromptTools {
+    var displayName: string;
+}
+export interface PromptToolProps extends Omit<ButtonProps, 'aria-pressed'> {
+    /** What it does, for a screen reader and for the tooltip. Shown beside the icon with `showLabel`. */
+    label: string;
+    /** Whether it is switched on, for a tool that stays on. Leave it out for one that acts once. */
+    pressed?: boolean;
+    /** Called with the new state when a tool with `pressed` is pressed. */
+    onPressedChange?: (pressed: boolean) => void;
+    /** Writes the label beside the icon. */
+    showLabel?: boolean;
+}
+/** A round button in the footer, holding an icon. With `pressed`, it switches on and off. */
+declare function PromptTool({ label, pressed, onPressedChange, showLabel, onClick, className, children, variant, ...props }: PromptToolProps): import("react").JSX.Element;
+declare namespace PromptTool {
+    var displayName: string;
+}
+export interface PromptAttachProps extends Omit<PromptToolProps, 'label' | 'pressed' | 'onPressedChange'> {
+    /** Default `Attach files`. */
+    label?: string;
+}
+/** A tool that opens the file picker. Files can also be pasted, or dropped on the field. */
+declare function PromptAttach({ label, onClick, children, ...props }: PromptAttachProps): import("react").JSX.Element;
+declare namespace PromptAttach {
+    var displayName: string;
+}
+export interface PromptModelItem {
+    value: string;
+    label: string;
+    /** Shown before the label, in the list and on the button once chosen. */
+    icon?: ReactNode;
+    /** A second line in the list. */
+    description?: ReactNode;
+}
+export interface PromptModelProps {
+    /** The models to choose from. */
+    items: readonly PromptModelItem[];
+    /** The chosen model, when the caller holds it. */
+    value?: string;
+    /** The model chosen to begin with, when the caller does not hold it. */
+    defaultValue?: string;
+    /** Called with the model's `value` when another is chosen. */
+    onValueChange?: (value: string) => void;
+    /** `pill` has an edge, like the tools beside it. `ghost` has none until hovered. Default `pill`. */
+    variant?: 'pill' | 'ghost';
+    /** What a screen reader calls the button. Default `Model`. */
+    label?: string;
+    className?: string;
+}
+/** Chooses the model the message goes to. The button shows the chosen one's icon and name. */
+declare function PromptModel({ items, value, defaultValue, onValueChange, variant, label, className, }: PromptModelProps): import("react").JSX.Element;
+declare namespace PromptModel {
+    var displayName: string;
+}
+export interface PromptMenuProps extends Omit<MenuContentProps, 'children'> {
+    /** What a screen reader and the tooltip call the button. Default `Add`. */
+    label?: string;
+    /** Replaces the plus on the button. */
+    icon?: ReactNode;
+    /** The menu: `Prompt.AttachItem`, and any `Menu` items, check items and submenus. */
+    children?: ReactNode;
+    /** `field` opens the menu as wide as the field, lined up with it, for items with descriptions. Default `auto`. */
+    width?: 'auto' | 'field';
+}
+/**
+ * One round button that opens a menu of everything that can be added to the
+ * message: files, tools, modes. It keeps the footer to one button however
+ * many there are.
+ */
+declare function PromptMenu({ label, icon, children, side, align, width, className, ...props }: PromptMenuProps): import("react").JSX.Element;
+declare namespace PromptMenu {
+    var displayName: string;
+}
+export interface PromptAttachItemProps extends Omit<MenuItemProps, 'children'> {
+    /** Default `Add files`. */
+    children?: ReactNode;
+    /** The keys shown at its end. Default `⌘U`; pass `null` for none. ⌘U and Ctrl+U in the field open the picker. */
+    shortcut?: ReactNode;
+}
+/** The menu item that opens the file picker. */
+declare function PromptAttachItem({ children, shortcut, onClick, ...props }: PromptAttachItemProps): import("react").JSX.Element;
+declare namespace PromptAttachItem {
+    var displayName: string;
+}
+export interface PromptSubmitProps extends Omit<ButtonProps, 'type' | 'children'> {
+    /** Makes the button a voice button while the field is empty. Called when it is pressed. */
+    onVoice?: () => void;
+    /** Whether voice is being heard. The bars move while it is. */
+    listening?: boolean;
+    /** What a screen reader calls the button while it sends. Default `Send`. */
+    sendLabel?: string;
+    /** While it stops the answer. Default `Stop`. */
+    stopLabel?: string;
+    /** While it starts voice. Default `Speak`. */
+    voiceLabel?: string;
+}
+/** Sends the message. While busy it stops the answer, and with `onVoice` it starts voice while the field is empty. */
+declare function PromptSubmit({ onVoice, listening, sendLabel, stopLabel, voiceLabel, onClick, className, disabled, ...props }: PromptSubmitProps): import("react").JSX.Element;
+declare namespace PromptSubmit {
+    var displayName: string;
+}
+export type PromptTaskStatus = 'pending' | 'active' | 'done' | 'error';
+export interface PromptTasksProps extends Omit<ComponentProps<'div'>, 'title'> {
+    /** Whether the band is shown. It folds under the field when it is not. Default `true`. */
+    open?: boolean;
+    /** What the agent is doing, on the band's one line: "Preparing the release". */
+    title: ReactNode;
+    /** Whether the list is open under the title, when the caller holds it. */
+    expanded?: boolean;
+    /** Whether the list starts open, when the caller does not hold it. Default `false`. */
+    defaultExpanded?: boolean;
+    /** Called when the title is pressed to open or close the list. */
+    onExpandedChange?: (expanded: boolean) => void;
+    /** How tall the list grows before it scrolls, as a CSS length. Default `10rem`. */
+    maxHeight?: string;
+}
+/**
+ * A band above the field with an agent's tasks: one line with a ring that
+ * fills as they are done, opening into the list. The list scrolls past
+ * `maxHeight`, and keeps the task in progress in view.
+ */
+declare function PromptTasks({ open, title, expanded, defaultExpanded, onExpandedChange, maxHeight, className, children, ...props }: PromptTasksProps): import("react").JSX.Element;
+declare namespace PromptTasks {
+    var displayName: string;
+}
+export interface PromptTaskProps extends ComponentProps<'li'> {
+    /** `pending`, `active` (its words are lit while it runs), `done` (a check) or `error`. Default `pending`. */
+    status?: PromptTaskStatus;
+}
+/** One task in `Prompt.Tasks`. */
+declare function PromptTask({ status, className, children, ...props }: PromptTaskProps): import("react").JSX.Element;
+declare namespace PromptTask {
+    var displayName: string;
+}
+export interface PromptCommandItem {
+    /** What is typed after the trigger to reach it: `summarise` for `/summarise`. */
+    value: string;
+    /** Its name in the list. Default the trigger and the value. */
+    label?: ReactNode;
+    /** What it does, after the name. */
+    description?: ReactNode;
+    icon?: ReactNode;
+}
+export interface PromptCommandsProps {
+    /** The commands. */
+    items: readonly PromptCommandItem[];
+    /** The character that opens the list when the field starts with it. Default `/`. */
+    trigger?: string;
+    /**
+     * Called with the command chosen. With it, the field is cleared and the
+     * command is yours to show; without it, the command is written into the field.
+     */
+    onSelect?: (item: PromptCommandItem) => void;
+    /** The heading over the list. Default `Commands`. */
+    label?: ReactNode;
+    /** How tall the list grows before it scrolls, as a CSS length. Default `12rem`. */
+    maxHeight?: string;
+}
+/**
+ * A band above the field listing commands while the text is a trigger and a
+ * word, `/sum`. The arrow keys move through it, Enter or Tab chooses, Escape
+ * puts it away.
+ */
+declare function PromptCommands({ items, trigger, onSelect, label, maxHeight }: PromptCommandsProps): import("react").JSX.Element;
+declare namespace PromptCommands {
+    var displayName: string;
+}
+export interface PromptRecorderProps extends ComponentProps<'div'> {
+    /** What has been heard so far, written in as it arrives. */
+    transcript?: ReactNode;
+    /** Shown, lit by a moving sweep, until there is a transcript. Default `Listening…`. */
+    placeholder?: ReactNode;
+    /** Called when the cross is pressed, to throw the recording away. */
+    onCancel?: () => void;
+    /** Called when the check is pressed, to keep it. */
+    onDone?: () => void;
+    /**
+     * How loud the input is now, from 0 to 1, to draw from a real microphone.
+     * Without it the wave moves on its own, as a sign that it is listening.
+     */
+    level?: number;
+    /** What a screen reader calls the cross. Default `Cancel recording`. */
+    cancelLabel?: string;
+    /** And the check. Default `Finish recording`. */
+    doneLabel?: string;
+}
+/**
+ * Takes the place of the text and the footer while voice is recorded: what
+ * has been heard so far, the sound as a wave scrolling to the left, how long
+ * it has been, and buttons to throw it away or keep it.
+ */
+declare function PromptRecorder({ transcript, placeholder, onCancel, onDone, level, cancelLabel, doneLabel, className, ...props }: PromptRecorderProps): import("react").JSX.Element;
+declare namespace PromptRecorder {
+    var displayName: string;
+}
+export declare const Prompt: typeof PromptRoot & {
+    Banner: typeof PromptBanner;
+    BannerAction: typeof PromptBannerAction;
+    Field: typeof PromptField;
+    Attachments: typeof PromptAttachments;
+    Textarea: typeof PromptTextarea;
+    Footer: typeof PromptFooter;
+    Tools: typeof PromptTools;
+    Tool: typeof PromptTool;
+    Attach: typeof PromptAttach;
+    Menu: typeof PromptMenu;
+    AttachItem: typeof PromptAttachItem;
+    Model: typeof PromptModel;
+    Submit: typeof PromptSubmit;
+    Status: typeof PromptStatus;
+    Tasks: typeof PromptTasks;
+    Task: typeof PromptTask;
+    Commands: typeof PromptCommands;
+    Recorder: typeof PromptRecorder;
+    Context: typeof PromptContext;
+    ContextItem: typeof PromptContextItem;
+    Hint: typeof PromptHint;
+};
+export { PromptBanner, PromptBannerAction, PromptField, PromptAttachments, PromptTextarea, PromptFooter, PromptTools, PromptTool, PromptAttach, PromptMenu, PromptAttachItem, PromptModel, PromptSubmit, PromptStatus, PromptTasks, PromptTask, PromptCommands, PromptRecorder, PromptContext, PromptContextItem, PromptHint, };