altitude-design 0.2.1 → 0.3.0

package/dist/types/prompt-input.d.ts

@@ -0,0 +1,106 @@
+import * as React from 'react';
+export type PromptStatus = 'ready' | 'submitted' | 'streaming' | 'error';
+export interface PromptAttachment {
+    id: string;
+    file: File;
+    name: string;
+    status?: 'pending';
+}
+export interface PromptMention {
+    id: string;
+    label: string;
+    kind?: 'file' | 'record' | 'person';
+    description?: string;
+}
+export interface PromptCommand {
+    name: string;
+    description?: string;
+}
+export interface PromptMessage {
+    text: string;
+    files: File[];
+    /** What was pointed at with @ and is still in the text. */
+    mentions?: PromptMention[];
+    /** The command chosen with / at the start, without its slash; it's taken out of `text`. */
+    command?: string;
+}
+export interface PromptInputProps extends Omit<React.FormHTMLAttributes<HTMLFormElement>, 'onSubmit'> {
+    /** Called with the text and attached files when sent. */
+    onSubmit: (message: PromptMessage) => void;
+    /** 'submitted' and 'streaming' turn Send into Stop, in the same slot. Default 'ready'. */
+    status?: PromptStatus;
+    onStop?: () => void;
+    /**
+     * Lets a person queue a message while the agent works (#276): Enter while 'submitted' or 'streaming' calls this
+     * instead of doing nothing; the button stays Stop, the composer empties and keeps focus. Show the queue with
+     * ConversationQueue and send the first one when the turn ends.
+     */
+    onQueue?: (message: PromptMessage) => void;
+    /**
+     * Things to point the agent at (#283): typing @ opens a list of what matches, filtered as you type. A chosen one is
+     * "@label" in the text and a plate above it; Backspace after it removes it whole. A promise shows "Searching…".
+     */
+    mentionable?: (query: string) => PromptMention[] | Promise<PromptMention[]>;
+    /** Commands: typing / at the start of an empty composer opens them ("/review"). */
+    commands?: PromptCommand[];
+    /** Controlled text. */
+    value?: string;
+    onValueChange?: (text: string) => void;
+    /** Called when files are attached; a promise holds the chip as pending ("Uploading") until it settles, a rejection removes it. */
+    onAttach?: (files: File[]) => void | Promise<unknown>;
+    /** Accepted file types, as for an input. Leave out to turn attachments off for the picker and drop. */
+    accept?: string;
+    children: React.ReactNode;
+}
+/**
+ * Where a person writes to an agent. The whole composer is an opening, the Input well: empty it shows its back wall and
+ * deepens as the pointer nears, and once it holds text the floor rises flush. Send is the level-2 primary; while a
+ * response is generating it becomes Stop in the same slot and size, so nothing moves. Enter sends, Shift+Enter adds a
+ * line, and Enter during IME composition never sends.
+ */
+export declare function PromptInput({ onSubmit, status, onStop, onQueue, mentionable, commands, value, onValueChange, onAttach, accept, className, children, ...rest }: PromptInputProps): React.JSX.Element;
+export interface PromptInputTextareaProps extends Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, 'value' | 'onChange'> {
+    /** The tallest it grows, in pixels, before it scrolls. Default 200. */
+    maxHeight?: number;
+}
+/** The text: it grows with what's written, up to maxHeight, then scrolls. */
+export declare function PromptInputTextarea({ placeholder, maxHeight, className, onKeyDown, 'aria-label': label, ...rest }: PromptInputTextareaProps): React.JSX.Element;
+/** The attached files as Tag plates; one being uploaded hovers as pending. */
+export declare function PromptInputAttachments({ className }: {
+    className?: string;
+}): React.JSX.Element | null;
+/** The row under the text: tools and pickers on the left, Send on the right. */
+export declare function PromptInputToolbar({ className, children }: {
+    className?: string;
+    children?: React.ReactNode;
+}): React.JSX.Element;
+/** Attach files (the picker); ⌘/Ctrl+U does the same from the text. Needs `accept` on PromptInput. */
+export declare function PromptInputAttach({ label }: {
+    label?: string;
+}): React.JSX.Element;
+export interface PromptInputDictateProps {
+    /** Default 'idle'. 'denied' and 'unavailable' keep the button focusable and say why it can't listen. */
+    status?: 'idle' | 'listening' | 'denied' | 'unavailable';
+    onStart?: () => void;
+    onStop?: () => void;
+    /** Words heard but not final: a ghost under the text in ink-faint, never in the value. */
+    interim?: string;
+    /** Final words to insert at the caret; give each result a new id. */
+    final?: {
+        id: string | number;
+        text: string;
+    };
+    /** Default "Dictate". */
+    label?: string;
+}
+/**
+ * Dictate a message (#284): a latched toggle. Listening is the Toggle's "on": a shallow well with accent-soft poured
+ * in, "Listening" and a steady lamp, with no pulse and no waveform. Interim words are a ghost like a suggestion; final
+ * words land at the caret. Blocked or unavailable stays focusable and says why. ⌘D / Ctrl+D toggles; Escape stops
+ * listening before it stops generating. Your app supplies the speech recognition.
+ */
+export declare function PromptInputDictate({ status, onStart, onStop, interim, final, label }: PromptInputDictateProps): React.JSX.Element;
+/** Send, which becomes Stop in the same slot and size while a response is generating. */
+export declare function PromptInputSubmit({ className }: {
+    className?: string;
+}): React.JSX.Element;

package/dist/types/property-list.d.ts

@@ -0,0 +1,67 @@
+import * as React from 'react';
+import { InlineEditControl, InlineEditSaveResult } from './inline-edit.js';
+import { EditRegionBinder, EditRegionSaveResult } from './edit-region.js';
+export interface PropertyListEditAll<T extends Record<string, unknown>> {
+    /** The whole record, edited together (for cross-field rules such as start before end). */
+    value: T;
+    onValueChange: (canonical: T) => void;
+    onSave: (draft: T, context: {
+        previousValue: T;
+        changed: (keyof T)[];
+    }) => EditRegionSaveResult<T> | Promise<EditRegionSaveResult<T>>;
+    validate?: (draft: T) => Partial<Record<keyof T, string>> | undefined | Promise<Partial<Record<keyof T, string>> | undefined>;
+    renderEditor: (field: EditRegionBinder<T>) => React.ReactNode;
+    /** Names the region and its button: “Edit all <label>”. Default “details”. */
+    label?: string;
+}
+export interface PropertyListProps<T extends Record<string, unknown> = Record<string, unknown>> {
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    /** stacked: label above value (a sidebar). inline: label beside value (a summary). Default 'stacked'. */
+    layout?: 'stacked' | 'inline';
+    /** Single-key shortcuts (an item's `shortcut`) while focus is in the list. Off by default (WCAG 2.1.4): offer a way to turn them on. */
+    shortcuts?: boolean;
+    /** An “Edit all” button that lifts the whole list into one EditRegion. */
+    editAll?: PropertyListEditAll<T>;
+    /** Who proposed the items' `proposed` values ("Assistant", "Maya"). Default "Assistant". */
+    proposedBy?: string;
+    className?: string;
+    children: React.ReactNode;
+}
+export interface PropertyListItemProps<V> {
+    label: string;
+    value: V;
+    /** Read mode. Default: the value as text. */
+    renderValue?: (value: V) => React.ReactNode;
+    /** An empty value's words, shown in a small well. Default “Not set”. */
+    emptyLabel?: string;
+    /** Makes the item editable (InlineEdit's contract). Without it, the value is read-only text. */
+    onSave?: (draft: V, context: {
+        previousValue: V;
+    }) => InlineEditSaveResult<V> | Promise<InlineEditSaveResult<V>>;
+    onValueChange?: (canonical: V) => void;
+    editor?: (control: InlineEditControl<V>) => React.ReactNode;
+    commit?: 'explicit' | 'on-choose';
+    validate?: (draft: V) => string | undefined | Promise<string | undefined>;
+    required?: boolean;
+    isEqual?: (a: V, b: V) => boolean;
+    /** A single key that opens this item while focus is in the list (with `shortcuts` on the list). Case doesn't matter. */
+    shortcut?: string;
+    /**
+     * A change someone proposes (an agent reading an email, a teammate's suggested edit): the current value with the
+     * proposed one beside it, raised, with Accept and Reject. Nothing touches the record until it's accepted; accepting
+     * saves through onSave (hovering as pending, then settling).
+     */
+    proposed?: V;
+    /** Called once the proposal is accepted (and saved) or rejected: clear `proposed` here. */
+    onProposalResolved?: (accepted: boolean, value: V) => void;
+    className?: string;
+}
+/**
+ * One record's properties as label–value pairs. The properties are the record, on the ground; an unset value is a
+ * small opening; an editable value is one plate that lifts when pointed at, because clicking it opens its editor
+ * (InlineEdit, with any control). “Edit all” lifts the whole list into one EditRegion for cross-field rules.
+ */
+export declare function PropertyList<T extends Record<string, unknown> = Record<string, unknown>>({ layout, shortcuts, editAll, proposedBy, className, children, ...aria }: PropertyListProps<T>): React.JSX.Element;
+/** One property. With onSave its value is an editable plate (InlineEdit); without, read-only text. */
+export declare function PropertyListItem<V>({ label, value, renderValue, emptyLabel, onSave, onValueChange, editor, commit, validate, required, isEqual, shortcut, proposed, onProposalResolved, className }: PropertyListItemProps<V>): React.JSX.Element;

package/dist/types/question.d.ts

@@ -0,0 +1,64 @@
+import * as React from 'react';
+export type QuestionState = 'asking' | 'answered' | 'expired';
+export interface QuestionAnswer {
+    values: string[];
+    other?: string;
+}
+export interface QuestionOptionProps {
+    value: string;
+    label: React.ReactNode;
+    description?: React.ReactNode;
+}
+/** One option of a Question. It renders nothing itself: the Question draws it as a radio or a checkbox. */
+export declare function QuestionOption(_: QuestionOptionProps): null;
+export interface QuestionProps {
+    /** The question, as its title: "Which environment should I deploy to?". */
+    title: string;
+    /** Default 'asking'. */
+    state?: QuestionState;
+    /** Several options may be chosen (checkboxes). Default false (a radio group). */
+    multiple?: boolean;
+    /** A one-line field for an answer of the person's own. */
+    allowOther?: boolean;
+    /** Default "Your own answer". */
+    otherLabel?: string;
+    /** Default "Answer". */
+    answerLabel?: string;
+    /** Shows a ghost button that lets the run go on without an answer: "Let the assistant decide". */
+    skipLabel?: string;
+    onSkip?: () => void;
+    onAnswer?: (answer: QuestionAnswer) => void;
+    /** What was answered, for the record once it's 'answered'. */
+    answer?: QuestionAnswer;
+    answeredAt?: Date | string | number;
+    /** Default "The assistant". */
+    requestedBy?: string;
+    /** Its key in a QuestionSet's answers. */
+    name?: string;
+    /** QuestionOptions. */
+    children: React.ReactNode;
+    className?: string;
+}
+/**
+ * An agent asks the person something before it carries on (#270): the elicitation half of human-in-the-loop. Nothing
+ * has been dispatched, so it's raised like a requested Confirmation, not pending. Options are a radio group (or
+ * checkboxes), "Your own answer" is a field, and Answer is the one primary; there's no default and nothing is focused
+ * for you. Answered, it presses to the ground as one line: "You chose: Staging · now".
+ */
+export declare function Question({ title, state: own, multiple, allowOther, otherLabel, answerLabel, skipLabel, onSkip, onAnswer, answer, answeredAt, requestedBy, name, children, className }: QuestionProps): React.JSX.Element;
+export interface QuestionSetProps {
+    /** Names the set: "The assistant has 2 questions". */
+    'aria-label'?: string;
+    state?: QuestionState;
+    /** Called with every Question's answer, by its name, when Answer is pressed. Answer waits until each has one. */
+    onAnswer?: (answers: Record<string, QuestionAnswer>) => void;
+    answerLabel?: string;
+    skipLabel?: string;
+    onSkip?: () => void;
+    requestedBy?: string;
+    /** Questions, each with a name. */
+    children: React.ReactNode;
+    className?: string;
+}
+/** Several questions in one request (AskUserQuestion allows up to four), answered together by one button. */
+export declare function QuestionSet({ 'aria-label': label, state, onAnswer, answerLabel, skipLabel, onSkip, requestedBy, children, className }: QuestionSetProps): React.JSX.Element;

package/dist/types/relative-time.d.ts

@@ -0,0 +1,21 @@
+import * as React from 'react';
+export interface RelativeTimeOptions {
+    /** 'relative' (default) always says "3 minutes ago"; 'auto' is relative within `threshold`, then a date ("Mar 4"). */
+    format?: 'relative' | 'auto';
+    /** For format="auto": how far from now stays relative. An ISO 8601 duration ("P7D", "PT12H") or milliseconds. Default "P7D". */
+    threshold?: string | number;
+    /** 'past' never says "in 2 minutes" (a clock running ahead shows "now"); 'future' never says "ago". Default 'auto'. */
+    tense?: 'auto' | 'past' | 'future';
+    /** Default: the browser's. */
+    locale?: string;
+}
+/** A moment as words relative to `now`, the way RelativeTime shows it: "3 minutes ago", "yesterday", "in 2 hours", "Mar 4". */
+export declare function formatRelativeTime(date: Date | string | number, now?: number, { format, threshold, tense, locale }?: RelativeTimeOptions): string;
+export interface RelativeTimeProps extends RelativeTimeOptions, Omit<React.TimeHTMLAttributes<HTMLElement>, 'children' | 'dateTime'> {
+    /** The moment. When it changes (the record was edited again) it settles with the afterglow; time passing doesn't. */
+    date: Date | string | number;
+    /** Show the exact date, time and zone in a Tooltip on hover and focus (the element becomes focusable). Default true. */
+    tooltip?: boolean;
+}
+/** A moment as "3 minutes ago" in a <time>, refreshed on one shared timer, with its exact time on hand. Ticking isn't a change. */
+export declare function RelativeTime({ date, format, threshold, tense, locale, tooltip, className, title, style, ...rest }: RelativeTimeProps): React.JSX.Element;