@theoremjs/studio 0.0.0-stage → 0.3.2

package/ui/inspector.d.ts

@@ -0,0 +1,247 @@
+import type { InputStatus } from '@astryxdesign/core/Field';
+import { type IconType } from '@astryxdesign/core/Icon';
+import { type SelectorOptionType } from '@astryxdesign/core/Selector';
+import { type ReactNode } from 'react';
+import type { SettingOrigin } from '../server/save-wire.ts';
+/**
+ * Controls the project's files set in code: they show their value and take no edit. A disabled
+ * fieldset turns off every control inside it, whatever kind it is.
+ */
+export declare function SetInCode({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * Under a value the files set in code: one quiet line saying what sets it. Clicking it opens that
+ * line in the builder's editor. Hovering shows the whole of it, with the full path to copy when
+ * no editor opens.
+ */
+export declare function OriginLine({ origin, onOpen }: {
+    origin: SettingOrigin;
+    onOpen: () => void;
+}): import("react").JSX.Element;
+/**
+ * A captioned group of rows. The panel stays at zero padding and each section carries the gutter.
+ * Transparent, so the panel's own surface shows through. The title shows the catalog entry of the
+ * field the section edits (`path`) on hover, as a row's label does. Under it, `note`: only what
+ * the catalog does not say, such as how the editor or the studio treats the field.
+ */
+export declare function InspectorSection({ title, path, note, children, }: {
+    title?: string;
+    path?: string;
+    note?: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * The name of a group of rows inside a section. Astryx's ladder, top down: the page title is 14
+ * bold, a section title 14 semibold, this 12 semibold in primary, a row label 12 regular in
+ * secondary. `hint` says what the group is, on hover.
+ */
+export declare function InspectorGroupTitle({ title, hint }: {
+    title: string;
+    hint?: string;
+}): import("react").JSX.Element;
+/**
+ * One row: the label column, then the controls for it. `path` is the field's schema catalog path;
+ * `hasIssue` marks the row for the issue pill. With `hasNote`, a note sits under the control, so the
+ * label stays beside the control and not halfway down the note.
+ */
+export declare function InspectorRow({ label, path, isRequired, hasIssue, hasNote, children, }: {
+    label: string;
+    path: string;
+    /** Notes "Required" under the label. */
+    isRequired?: boolean;
+    hasIssue?: boolean;
+    hasNote?: boolean;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** Says whether the row's field is required now, for one required only in some cases. */
+export type IsRequired = {
+    isRequired?: boolean;
+};
+/** What a field row takes: its label, its catalog path, and the draft field whose issues show on it. */
+export type FieldRowProps = {
+    label: string;
+    path: string;
+    /** The draft field whose issues show on this row. */
+    field?: string;
+} & IsRequired;
+/**
+ * Free text. Left blank, it shows `placeholder`, a value Tab takes up to edit (an example, or the
+ * default); else `hint`, or what leaving it out does.
+ */
+export declare function TextRow(props: FieldRowProps & {
+    value: string;
+    status?: InputStatus;
+    placeholder?: string;
+    hint?: string;
+    /** The most characters the field takes; typing stops there. */
+    maxLength?: number;
+    onChange: (next: string) => void;
+}): import("react").JSX.Element;
+/**
+ * Longer text, under its label rather than beside it: wording and JSON. Left blank, it shows
+ * `placeholder` (for wording, the kernel's own default line) for Tab to take up, else `hint`.
+ */
+export declare function TextAreaRow(props: FieldRowProps & {
+    value: string;
+    placeholder?: string;
+    hint?: string;
+    rows?: number;
+    hasSpellCheck?: boolean;
+    /** A status of the row's own, such as text that is not JSON; the field's issues win. */
+    status?: InputStatus;
+    onChange: (next: string) => void;
+}): import("react").JSX.Element;
+/** A number the kernel leaves unset when cleared: it gives `null`, shown as what leaving it out does. */
+export declare function NumberRow(props: FieldRowProps & {
+    value: number | null;
+    min?: number;
+    max?: number;
+    step?: number;
+    isIntegerOnly?: boolean;
+    /** Shown at the end of the input, e.g. `ms`. */
+    units?: string;
+    /** Shown while blank, in place of what leaving it out does. */
+    hint?: string;
+    /** A note of the row's own, such as what the value set does; the field's issues win. */
+    status?: InputStatus;
+    onChange: (next: number | null) => void;
+}): import("react").JSX.Element;
+/**
+ * A slider's value: one that is always set, or one that can be blank, whose thumb sits at
+ * `fallback` while it is.
+ */
+export type SliderValue = {
+    value: number;
+    fallback?: undefined;
+    onChange: (next: number) => void;
+} | {
+    value: number | null;
+    fallback: number;
+    onChange: (next: number | null) => void;
+};
+/**
+ * A number on a slider, shown by `format` (compact by default). One that can be blank sits at
+ * `fallback`, where the provider puts it, and reads "Default" until moved; reset puts it back.
+ */
+export declare function SliderRow(props: {
+    label: string;
+    path: string;
+    /** The draft field whose issues show on this row. */
+    field?: string;
+    min: number;
+    max: number;
+    step: number;
+    format?: (value: number) => string;
+} & SliderValue): import("react").JSX.Element;
+/** On or off. What leaving it out does shows on hover. */
+export declare function SwitchRow({ label, path, field, value, isDisabled, disabledMessage, onChange, }: {
+    label: string;
+    path: string;
+    /** The draft field whose issues show on this row. */
+    field?: string;
+    value: boolean;
+    isDisabled?: boolean;
+    /** Why it's off limits, on hover and focus, when `isDisabled`. */
+    disabledMessage?: string;
+    onChange: (next: boolean) => void;
+}): import("react").JSX.Element;
+export interface Segment<T extends string> {
+    value: T;
+    label: string;
+    icon: IconType;
+    /** What it means, on hover, for a segment the catalog has no option for. */
+    description?: string;
+    isDisabled?: boolean;
+    /** Why it can't be picked, on hover, when `isDisabled`. */
+    disabledMessage?: string;
+    /** The pick the kernel recommends here: its name says so, on hover and to a screen reader. */
+    isRecommended?: boolean;
+}
+export type SegmentedRowProps<T extends string> = {
+    label: string;
+    path: string;
+    /** The draft field whose issues show on this row. */
+    field?: string;
+    value: T;
+    segments: readonly Segment<T>[];
+    isDisabled?: boolean;
+    warning?: string;
+    /** A status of the row's own, such as an issue on a page the row opens; the field's issues win. */
+    status?: InputStatus;
+    /** A control after the segments, on the same line. */
+    trailing?: ReactNode;
+    /** Past this many options, the row is a dropdown of the same options rather than segments. */
+    selectorPast?: number;
+    onChange: (next: T) => void;
+} & IsRequired;
+/**
+ * A closed set, as icon segments, or a dropdown of the same options past `selectorPast`. Each
+ * option's label is its accessible name, and it shows with the schema's description of that
+ * option, on hover as a segment or under it in the list. `warning` says, under it, when the pick is
+ * valid but won't do what it looks like; a compile issue on the row shows instead.
+ */
+export declare function SegmentedRow<T extends string>({ label, path, field, value, segments, isDisabled, isRequired, warning, status: given, trailing, selectorPast, onChange, }: SegmentedRowProps<T>): import("react").JSX.Element;
+/** One option of a `ChoiceRow`: its value alone, or with a label, a description, or disabled. */
+export type Choice<T extends string> = T | {
+    value: T;
+    label?: string;
+    description?: string;
+    disabled?: boolean;
+};
+export type ChoiceRowProps<T extends string> = {
+    label: string;
+    path: string;
+    /** The draft field whose issues show on this row. */
+    field?: string;
+    value: T | '';
+    options: readonly Choice<T>[];
+    isDisabled?: boolean;
+    hasSearch?: boolean;
+    /** The options are still arriving. */
+    isLoading?: boolean;
+    /** What an empty list says. */
+    emptyText?: string;
+    /** What the blank row says, in place of what leaving the field out does. */
+    placeholder?: string;
+    /** A status of the row's own, such as a list that failed to load; the field's issues win. */
+    status?: InputStatus;
+    /** Each option's description shows on hover, not under its name: for long ones, such as a protocol's. */
+    hasHoverDescriptions?: boolean;
+    onChange: (next: T | '') => void;
+} & IsRequired;
+/**
+ * A choice from a list, `''` when none is chosen. An optional one can be cleared, and shows what
+ * leaving it out does while blank. `hasSearch` filters a long list. A value the list leaves out
+ * shows as itself, marked "Not in the list", so a list never hides or rewrites what the file says.
+ */
+export declare function ChoiceRow<T extends string>({ label, path, field, value, options, isDisabled, isRequired, hasSearch, isLoading, emptyText, placeholder, status: given, hasHoverDescriptions, onChange, }: ChoiceRowProps<T>): import("react").JSX.Element;
+/**
+ * Several choices from a list, the first few as badges and the rest counted (`ListBadges`): the
+ * trigger is one line tall, and Astryx wraps badges past it. Left empty, it shows what leaving it
+ * out does.
+ */
+export declare function ListRow({ label, path, field, value, options, onChange, }: {
+    label: string;
+    path: string;
+    /** The draft field whose issues show on this row. */
+    field?: string;
+    value: string[];
+    options: SelectorOptionType[];
+    onChange: (next: string[]) => void;
+}): import("react").JSX.Element;
+/**
+ * Free-form names, typed and committed with Enter, each a token. Duplicates and blanks never make
+ * it in. `disabledMessage` says why, when `isDisabled`.
+ */
+export declare function NamesRow({ label, path, field, value, placeholder, isDisabled, disabledMessage, onChange, }: {
+    label: string;
+    path: string;
+    /** The draft field whose issues show on this row. */
+    field?: string;
+    value: string[];
+    placeholder?: string;
+    isDisabled?: boolean;
+    disabledMessage?: string;
+    onChange: (next: string[]) => void;
+}): import("react").JSX.Element;

package/ui/inspector.js

@@ -0,0 +1,284 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { FieldStatus } from '@astryxdesign/core/FieldStatus';
+import { HoverCard } from '@astryxdesign/core/HoverCard';
+import { HStack } from '@astryxdesign/core/HStack';
+import { useClipboard } from '@astryxdesign/core/hooks';
+import { Icon } from '@astryxdesign/core/Icon';
+import { IconButton } from '@astryxdesign/core/IconButton';
+import { MultiSelector } from '@astryxdesign/core/MultiSelector';
+import { NumberInput } from '@astryxdesign/core/NumberInput';
+import { Section } from '@astryxdesign/core/Section';
+import { SegmentedControl, SegmentedControlItem } from '@astryxdesign/core/SegmentedControl';
+import { Selector, SelectorOption, } from '@astryxdesign/core/Selector';
+import { Slider } from '@astryxdesign/core/Slider';
+import { StackItem } from '@astryxdesign/core/Stack';
+import { Switch } from '@astryxdesign/core/Switch';
+import { Text } from '@astryxdesign/core/Text';
+import { TextArea } from '@astryxdesign/core/TextArea';
+import { TextInput } from '@astryxdesign/core/TextInput';
+import { Token } from '@astryxdesign/core/Token';
+import { Tokenizer } from '@astryxdesign/core/Tokenizer';
+import { Tooltip } from '@astryxdesign/core/Tooltip';
+import { VStack } from '@astryxdesign/core/VStack';
+import { IconArrowBackUp, IconCheck, IconCode, IconCopy } from '@tabler/icons-react';
+import { fieldMeta } from '@theoremjs/agents';
+import { useContext } from 'react';
+import { originLabel, originPlace, originShortLabel, STUDIO_PROFILE_TYPES } from "../mod.js";
+import { ISSUE_ROW_ATTRIBUTE, ListBadges, SaidOrigin, useFieldStatus, useRowOrigin, } from "./inspector-context.js";
+import { tabFills } from "./lib/tab-fills.js";
+/**
+ * Inspector building blocks: captioned sections of label-and-control rows, after Astryx's
+ * canvas editor template. Every control is `sm` and hides its own label, because the row's
+ * label column names it; that column is one fixed width, so every control starts on one edge.
+ */
+/**
+ * The label column, wide enough for the longest label ("Temperature", "Attachments") on one line.
+ * The template's is 80, which fits its shorter labels.
+ */
+const LABEL_COLUMN = 96;
+/**
+ * Whether the field at `path` must be set, and what leaving it out does, from the kernel's catalog.
+ * `isRequired` overrides it for a field required only in some cases, saying whether it is now.
+ */
+function presence(path, isRequired) {
+    const meta = fieldMeta(path);
+    const required = isRequired ?? meta?.required === true;
+    return { required, unset: required ? undefined : meta?.unset };
+}
+/**
+ * Controls the project's files set in code: they show their value and take no edit. A disabled
+ * fieldset turns off every control inside it, whatever kind it is.
+ */
+export function SetInCode({ children }) {
+    return (_jsx("fieldset", { disabled: true, className: "inspector-set-in-code", children: children }));
+}
+/**
+ * Under a value the files set in code: one quiet line saying what sets it. Clicking it opens that
+ * line in the builder's editor. Hovering shows the whole of it, with the full path to copy when
+ * no editor opens.
+ */
+export function OriginLine({ origin, onOpen }) {
+    const { copy, isCopied } = useClipboard();
+    const place = originPlace(origin);
+    const label = originLabel(origin);
+    const line = (_jsxs(_Fragment, { children: [_jsx(Icon, { icon: IconCode, size: "sm" }), _jsx("span", { className: "inspector-origin-text", children: originShortLabel(origin) })] }));
+    return (_jsx(HoverCard, { label: place ? `${label} · ${place}` : label, hasHoverIndication: false, className: "inspector-origin-trigger", content: _jsxs(VStack, { gap: 1, children: [_jsx(Text, { type: "supporting", children: label }), place && (_jsxs(HStack, { gap: 2, vAlign: "center", children: [_jsx(Text, { type: "code", size: "sm", children: place }), _jsx(IconButton, { label: isCopied ? 'Copied' : 'Copy path', variant: "ghost", size: "sm", icon: _jsx(Icon, { icon: isCopied ? IconCheck : IconCopy, size: "sm" }), onClick: () => {
+                                copy(place);
+                            } })] }))] }), children: place ? (_jsx("button", { type: "button", className: "inspector-origin", onClick: onOpen, children: line })) : (_jsx("div", { className: "inspector-origin", children: line })) }));
+}
+/**
+ * A captioned group of rows. The panel stays at zero padding and each section carries the gutter.
+ * Transparent, so the panel's own surface shows through. The title shows the catalog entry of the
+ * field the section edits (`path`) on hover, as a row's label does. Under it, `note`: only what
+ * the catalog does not say, such as how the editor or the studio treats the field.
+ */
+export function InspectorSection({ title, path, note, children, }) {
+    const heading = title && (_jsx(Text, { type: "label", weight: "semibold", children: title }));
+    // A section whose own field the files set in code says so once, and its rows take no edit.
+    const found = useRowOrigin(path);
+    const says = found && !found.said ? found : undefined;
+    return (_jsx(Section, { variant: "transparent", padding: 3, children: _jsxs(VStack, { gap: 3, children: [_jsxs(VStack, { gap: 1, hAlign: "start", children: [heading && title && path !== undefined ? (_jsx(CatalogHover, { label: title, path: path, children: heading })) : (heading), note && _jsx(Text, { type: "supporting", children: note })] }), says ? (_jsxs(SaidOrigin, { value: says.origin, children: [_jsx(OriginLine, { origin: says.origin, onOpen: says.open }), _jsx(SetInCode, { children: _jsx(VStack, { gap: 3, children: children }) })] })) : (children)] }) }));
+}
+/**
+ * The name of a group of rows inside a section. Astryx's ladder, top down: the page title is 14
+ * bold, a section title 14 semibold, this 12 semibold in primary, a row label 12 regular in
+ * secondary. `hint` says what the group is, on hover.
+ */
+export function InspectorGroupTitle({ title, hint }) {
+    const heading = (_jsx(Text, { type: "supporting", weight: "semibold", color: "primary", children: title }));
+    return hint ? _jsx(Tooltip, { content: hint, children: heading }) : heading;
+}
+/**
+ * `children`, with the schema's entry for `path` on hover: what it does, then its options as
+ * tokens (or its type, when it has none), when it's required or what leaving it out does. The
+ * profile types that take it are only named when one the studio offers can't.
+ */
+function CatalogHover({ label, path, children, }) {
+    const meta = fieldMeta(path);
+    if (!meta)
+        return children;
+    const scope = meta.profileTypes;
+    // why: Decisions are the odd one out: they take little of the schema, so "not on decisions" is
+    // assumed, and only a narrower scope is worth saying.
+    const agents = STUDIO_PROFILE_TYPES.filter((type) => type !== 'decision');
+    const takes = agents.filter((type) => !scope || scope.includes(type));
+    const scoped = takes.length < agents.length ? takes : undefined;
+    return (_jsx(HoverCard, { label: label, content: _jsxs(VStack, { gap: 2, maxWidth: 280, children: [_jsx(Text, { children: meta.doc }), _jsx(HStack, { gap: 1, wrap: "wrap", children: (meta.options ?? [meta.type]).map((option) => (_jsx(Token, { label: option, size: "sm" }, option))) }), meta.optionNote && (_jsx(Text, { type: "supporting", color: "secondary", children: meta.optionNote })), typeof meta.required === 'string' && (_jsx(Text, { type: "supporting", color: "secondary", children: `Required ${meta.required}.` })), meta.unset && (_jsx(Text, { type: "supporting", color: "secondary", children: `Left out: ${meta.unset}.` })), scoped && (_jsx(Text, { type: "supporting", color: "secondary", children: `Only on ${scoped.join(', ')} profiles.` }))] }), children: children }));
+}
+/** A row's label, 12 regular in secondary, with "Required" under it when `isRequired`, and its catalog entry on hover. */
+function RowLabel({ label, path, isRequired, }) {
+    return (_jsx(CatalogHover, { label: label, path: path, children: _jsxs(VStack, { gap: 0, children: [_jsx(Text, { type: "supporting", color: "secondary", children: label }), isRequired && (_jsx(Text, { type: "supporting", color: "placeholder", children: "Required" }))] }) }));
+}
+/** The height of a row's control, which its label centres on when a note makes the row taller. */
+const CONTROL_HEIGHT = 28;
+/**
+ * One row: the label column, then the controls for it. `path` is the field's schema catalog path;
+ * `hasIssue` marks the row for the issue pill. With `hasNote`, a note sits under the control, so the
+ * label stays beside the control and not halfway down the note.
+ */
+export function InspectorRow({ label, path, isRequired = false, hasIssue, hasNote = false, children, }) {
+    // A value the files set in code shows, takes no edit, and says where it is set. A row inside a
+    // section or a node that already said so only takes no edit.
+    const found = useRowOrigin(path);
+    const set = found && !found.said ? found : undefined;
+    const tall = hasNote || set !== undefined;
+    const row = (_jsx(HStack, { gap: 1, vAlign: hasNote ? 'start' : 'center', children: children }));
+    const controls = found ? _jsx(SetInCode, { children: row }) : row;
+    return (_jsxs(HStack, { gap: 2, vAlign: tall ? 'start' : 'center', [ISSUE_ROW_ATTRIBUTE]: hasIssue || undefined, children: [_jsx(StackItem, { size: "static", children: _jsx(HStack, { width: LABEL_COLUMN, minHeight: tall ? CONTROL_HEIGHT : undefined, vAlign: "center", children: _jsx(RowLabel, { label: label, path: path, isRequired: isRequired }) }) }), _jsx(StackItem, { size: "fill", children: set ? (_jsxs(VStack, { gap: 1, children: [controls, _jsx(OriginLine, { origin: set.origin, onOpen: set.open })] })) : (controls) })] }));
+}
+/**
+ * A field row's issue status and presence, and the props its one control shares: labelled but with
+ * the label hidden, since the row shows it.
+ */
+function useFieldRow({ label, path, field, isRequired }) {
+    const status = useFieldStatus()(field);
+    const { required, unset } = presence(path, isRequired);
+    const control = { label, status, isLabelHidden: true, isRequired: required, size: 'sm' };
+    return { status, required, unset, control };
+}
+/** A field row whose one control fills the width beside the label. */
+function FillRow({ label, path, required, status, note, children, }) {
+    return (_jsx(InspectorRow, { label: label, path: path, isRequired: required, hasIssue: status !== undefined, hasNote: Boolean((status ?? note)?.message), children: _jsx(StackItem, { size: "fill", children: children }) }));
+}
+/**
+ * Free text. Left blank, it shows `placeholder`, a value Tab takes up to edit (an example, or the
+ * default); else `hint`, or what leaving it out does.
+ */
+export function TextRow(props) {
+    const { status: fieldStatus, required, unset, control } = useFieldRow(props);
+    const status = props.status ?? fieldStatus;
+    return (_jsx(FillRow, { label: props.label, path: props.path, required: required, status: status, children: _jsx(TextInput, { ...control, status: status, value: props.value, placeholder: props.placeholder ?? props.hint ?? unset, onKeyDown: tabFills(props.value, props.placeholder, props.onChange), 
+            // why: TextInput takes no maxLength, so what is typed or pasted past it is dropped here.
+            onChange: (next) => {
+                props.onChange(Array.from(next).slice(0, props.maxLength).join(''));
+            } }) }));
+}
+/**
+ * Longer text, under its label rather than beside it: wording and JSON. Left blank, it shows
+ * `placeholder` (for wording, the kernel's own default line) for Tab to take up, else `hint`.
+ */
+export function TextAreaRow(props) {
+    const { label, path, value, placeholder, hint, rows = 3, hasSpellCheck = true, onChange } = props;
+    const { status: fieldStatus, required, unset, control } = useFieldRow(props);
+    const status = fieldStatus ?? props.status;
+    return (_jsxs(VStack, { gap: 1, [ISSUE_ROW_ATTRIBUTE]: fieldStatus !== undefined || undefined, children: [_jsx(RowLabel, { label: label, path: path, isRequired: required }), _jsx(TextArea, { ...control, status: status, rows: rows, hasSpellCheck: hasSpellCheck, value: value, placeholder: placeholder ?? hint ?? unset, onKeyDown: tabFills(value, placeholder, onChange), onChange: onChange })] }));
+}
+/** A number the kernel leaves unset when cleared: it gives `null`, shown as what leaving it out does. */
+export function NumberRow(props) {
+    const { status, required, unset, control } = useFieldRow(props);
+    return (_jsx(FillRow, { label: props.label, path: props.path, required: required, status: status, note: props.status, children: _jsx(NumberInput, { ...control, status: status ?? props.status, value: props.value, placeholder: props.hint ?? unset, min: props.min, max: props.max, step: props.step, isIntegerOnly: props.isIntegerOnly, units: props.units, isWheelEnabled: false, hasClear: true, onChange: props.onChange }) }));
+}
+const COMPACT = new Intl.NumberFormat('en-US', { notation: 'compact' });
+/**
+ * A number on a slider, shown by `format` (compact by default). One that can be blank sits at
+ * `fallback`, where the provider puts it, and reads "Default" until moved; reset puts it back.
+ */
+export function SliderRow(props) {
+    const { label, path, field, min, max, step, format = (next) => COMPACT.format(next), } = props;
+    const status = useFieldStatus()(field);
+    const { required } = presence(path);
+    return (_jsxs(InspectorRow, { label: label, path: path, isRequired: required, hasIssue: status !== undefined, hasNote: Boolean(status?.message), children: [_jsx(StackItem, { size: "fill", children: _jsx(Slider, { label: label, status: status, isLabelHidden: true, value: props.fallback === undefined ? props.value : (props.value ?? props.fallback), min: min, max: max, step: step, valueDisplay: "text", formatValue: (next) => (props.value === null ? 'Default' : format(next)), onChange: props.onChange }) }), props.fallback !== undefined && (_jsx(IconButton, { label: `Reset ${label.toLowerCase()} to the provider default`, variant: "ghost", size: "sm", isDisabled: props.value === null, icon: _jsx(Icon, { icon: IconArrowBackUp, size: "sm" }), onClick: () => {
+                    props.onChange(null);
+                } }))] }));
+}
+/** On or off. What leaving it out does shows on hover. */
+export function SwitchRow({ label, path, field, value, isDisabled, disabledMessage, onChange, }) {
+    const status = useFieldStatus()(field);
+    return (_jsx(InspectorRow, { label: label, path: path, hasIssue: status !== undefined, hasNote: Boolean(status?.message), children: _jsx(Switch, { label: label, status: status, isLabelHidden: true, size: "sm", value: value, isDisabled: isDisabled, disabledMessage: disabledMessage, onChange: onChange }) }));
+}
+/**
+ * A closed set, as icon segments, or a dropdown of the same options past `selectorPast`. Each
+ * option's label is its accessible name, and it shows with the schema's description of that
+ * option, on hover as a segment or under it in the list. `warning` says, under it, when the pick is
+ * valid but won't do what it looks like; a compile issue on the row shows instead.
+ */
+export function SegmentedRow({ label, path, field, value, segments, isDisabled, isRequired, warning, status: given, trailing, selectorPast, onChange, }) {
+    const options = fieldMeta(path)?.optionDescriptions;
+    const issue = useFieldStatus()(field) ?? given;
+    const status = issue ?? (warning ? { type: 'warning', message: warning } : undefined);
+    const { required } = presence(path, isRequired);
+    const named = (segment) => segment.isRecommended ? `${segment.label} (recommended)` : segment.label;
+    const described = (segment) => (segment.isDisabled && segment.disabledMessage) ||
+        options?.[segment.value] ||
+        segment.description;
+    const choose = (next) => {
+        const segment = segments.find((candidate) => candidate.value === next);
+        if (segment)
+            onChange(segment.value);
+    };
+    return (_jsxs(InspectorRow, { label: label, path: path, isRequired: required, hasIssue: issue !== undefined, hasNote: Boolean(status?.message), children: [_jsxs(StackItem, { size: "fill", children: [selectorPast !== undefined && segments.length > selectorPast ? (_jsx(Selector, { label: label, isLabelHidden: true, isRequired: true, size: "sm", placement: "below", value: value, isDisabled: isDisabled, options: segments.map((segment) => ({
+                            value: segment.value,
+                            label: named(segment),
+                            icon: segment.icon,
+                            disabled: segment.isDisabled,
+                            description: described(segment),
+                        })), onChange: choose })) : (_jsx(SegmentedControl, { label: label, size: "sm", layout: "fill", value: value, isDisabled: isDisabled, onChange: choose, children: segments.map((segment) => {
+                            const description = described(segment);
+                            const name = named(segment);
+                            return (_jsx(Tooltip, { content: description ? `${name}: ${description}` : name, children: _jsx(SegmentedControlItem, { value: segment.value, label: name, isLabelHidden: true, isDisabled: segment.isDisabled, icon: _jsx(Icon, { icon: segment.icon, size: "sm" }) }) }, segment.value));
+                        }) })), status?.message && (_jsx(FieldStatus, { type: status.type, message: status.message, variant: "detached" }))] }), trailing] }));
+}
+/**
+ * A choice from a list, `''` when none is chosen. An optional one can be cleared, and shows what
+ * leaving it out does while blank. `hasSearch` filters a long list. A value the list leaves out
+ * shows as itself, marked "Not in the list", so a list never hides or rewrites what the file says.
+ */
+export function ChoiceRow({ label, path, field, value, options, isDisabled, isRequired, hasSearch, isLoading, emptyText, placeholder, status: given, hasHoverDescriptions, onChange, }) {
+    const status = useFieldStatus()(field) ?? given;
+    const { required, unset } = presence(path, isRequired);
+    const listed = options.some((option) => (typeof option === 'string' ? option : option.value) === value);
+    const held = value && !listed
+        ? [{ value, label: value, description: 'Not in the list' }, ...options]
+        : options;
+    // The Selector hands back a plain string; take the option's own value for it.
+    const choose = (next) => {
+        const chosen = held
+            .map((option) => (typeof option === 'string' ? option : option.value))
+            .find((candidate) => candidate === next);
+        onChange(chosen ?? '');
+    };
+    const shared = {
+        label,
+        status,
+        isLabelHidden: true,
+        size: 'sm',
+        options: [...held],
+        placement: 'below',
+        isDisabled,
+        hasSearch,
+        isLoading,
+        emptyText,
+        ...(hasHoverDescriptions ? { renderOption: hoverDescribed } : {}),
+    };
+    return (_jsx(InspectorRow, { label: label, path: path, isRequired: required, hasIssue: status !== undefined, hasNote: Boolean(status?.message), children: _jsx(StackItem, { size: "fill", children: required ? (_jsx(Selector, { ...shared, isRequired: true, value: value, placeholder: placeholder, onChange: choose })) : (_jsx(Selector, { ...shared, value: value || null, placeholder: placeholder ?? unset, hasClear: true, onChange: choose })) }) }));
+}
+/** An option named on its row, with its description in a tooltip. */
+function hoverDescribed(option) {
+    const row = _jsx(SelectorOption, { label: option.label ?? option.value });
+    return option.description ? (_jsx(Tooltip, { content: option.description, placement: "end", children: row })) : (row);
+}
+/**
+ * Several choices from a list, the first few as badges and the rest counted (`ListBadges`): the
+ * trigger is one line tall, and Astryx wraps badges past it. Left empty, it shows what leaving it
+ * out does.
+ */
+export function ListRow({ label, path, field, value, options, onChange, }) {
+    const status = useFieldStatus()(field);
+    const { unset } = presence(path);
+    const maxBadges = useContext(ListBadges);
+    return (_jsx(InspectorRow, { label: label, path: path, hasIssue: status !== undefined, hasNote: Boolean(status?.message), children: _jsx(StackItem, { size: "fill", children: _jsx(MultiSelector, { label: label, status: status, isLabelHidden: true, size: "sm", value: value, options: options, placeholder: unset, hasSearch: true, triggerDisplay: "badges", maxBadges: maxBadges, controlClassName: "inspector-list", onChange: onChange }) }) }));
+}
+/** A names row suggests nothing; every token is one the user typed. */
+const NO_SUGGESTIONS = { search: () => [], bootstrap: () => [] };
+/**
+ * Free-form names, typed and committed with Enter, each a token. Duplicates and blanks never make
+ * it in. `disabledMessage` says why, when `isDisabled`.
+ */
+export function NamesRow({ label, path, field, value, placeholder, isDisabled, disabledMessage, onChange, }) {
+    const status = useFieldStatus()(field);
+    const { unset } = presence(path);
+    return (_jsx(InspectorRow, { label: label, path: path, hasIssue: status !== undefined, hasNote: Boolean(status?.message), children: _jsx(StackItem, { size: "fill", children: _jsx(Tokenizer, { label: label, status: status, isLabelHidden: true, size: "sm", value: value.map((name) => ({ id: name, label: name })), searchSource: NO_SUGGESTIONS, hasCreate: true, debounceMs: 0, placeholder: placeholder ?? unset, isDisabled: isDisabled, disabledMessage: disabledMessage, tokenOverflowBehavior: "unfocusedInline", onChange: (items) => {
+                    const names = items.map((item) => item.label.trim()).filter(Boolean);
+                    onChange([...new Set(names)]);
+                } }) }) }));
+}

package/ui/lib/acting-as.d.ts

@@ -0,0 +1,25 @@
+import { type StudioActingAs, type StudioPeopleOffer, type StudioPerson } from '../../people.ts';
+import type { ProjectSession } from './studio-project.ts';
+export interface ActingAsState {
+    /** What the setup file offers; none when it offers no people. */
+    offer: StudioPeopleOffer | undefined;
+    /** Why the people the setup file exports cannot be offered. */
+    problem: string | undefined;
+    /** Who runs act as now; none is no one. */
+    actingAs: StudioActingAs | undefined;
+    choose: (next: StudioActingAs | undefined) => void;
+}
+/** Set by the studio while a project is open. Without it, every run acts as no one. */
+export declare const ActingAsContext: import("react").Context<ActingAsState>;
+export declare function useActingAs(): ActingAsState;
+/**
+ * The pick for a project: the builder's last one in this tab, else the one the setup file starts
+ * on, else no one. A pick in a place the setup no longer offers is no one.
+ */
+export declare function useActingAsState(project: ProjectSession | null): ActingAsState;
+/** Where an agent's chat is kept for a pick: no one's is the agent's own, each person's beside it. */
+export declare function chatKeyOf(chatWith: string, actingAs: StudioActingAs | undefined): string;
+/** The people already in `place` that the setup file offers. */
+export declare function listPeople(project: ProjectSession, place: string): Promise<StudioPerson[]>;
+/** A new person the setup file makes in `place`. */
+export declare function freshPerson(project: ProjectSession, place: string): Promise<StudioPerson>;

package/ui/lib/acting-as.js

@@ -0,0 +1,90 @@
+/**
+ * Who the project's runs act as: the builder's pick of a person in a place, from the people the
+ * setup file offers. Settings is where it is picked; every run carries it to the project, and each
+ * person keeps a chat of their own. The pick is kept in this tab, beside the chats it keys.
+ */
+import { createContext, useCallback, useContext, useMemo, useState } from 'react';
+import { actingAsSession, readPerson, readPick, } from "../../people.js";
+import { isRecord, session, WORKSPACE_KEY } from "./studio-session.js";
+const NO_PEOPLE = {
+    offer: undefined,
+    problem: undefined,
+    actingAs: undefined,
+    choose: () => undefined,
+};
+/** Set by the studio while a project is open. Without it, every run acts as no one. */
+export const ActingAsContext = createContext(NO_PEOPLE);
+export function useActingAs() {
+    return useContext(ActingAsContext);
+}
+const pickKey = (project) => `${WORKSPACE_KEY}.acting-as:${project}`;
+/** The builder's last pick in this tab: `null` for no one, nothing when they never picked. */
+function keptPick(project) {
+    try {
+        const raw = session()?.getItem(pickKey(project));
+        return raw ? { value: JSON.parse(raw) } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function keepPick(project, pick) {
+    try {
+        session()?.setItem(pickKey(project), JSON.stringify(pick));
+    }
+    catch {
+        // Storage refused: the pick lasts as long as the page.
+    }
+}
+/**
+ * The pick for a project: the builder's last one in this tab, else the one the setup file starts
+ * on, else no one. A pick in a place the setup no longer offers is no one.
+ */
+export function useActingAsState(project) {
+    const name = project?.name;
+    const offer = project?.people;
+    const problem = project?.peopleProblem;
+    const [chosen, setChosen] = useState(() => (name ? keptPick(name) : undefined));
+    const actingAs = useMemo(() => {
+        if (!offer)
+            return undefined;
+        const value = chosen ? chosen.value : offer.start;
+        if (value === null || value === undefined)
+            return undefined;
+        const read = readPick(value, offer.places);
+        return read.ok ? read.actingAs : undefined;
+    }, [offer, chosen]);
+    const choose = useCallback((next) => {
+        setChosen({ value: next ?? null });
+        if (name)
+            keepPick(name, next ?? null);
+    }, [name]);
+    return useMemo(() => (offer || problem ? { offer, problem, actingAs, choose } : NO_PEOPLE), [offer, problem, actingAs, choose]);
+}
+/** Where an agent's chat is kept for a pick: no one's is the agent's own, each person's beside it. */
+export function chatKeyOf(chatWith, actingAs) {
+    return actingAs ? `${chatWith}@${actingAsSession(actingAs)}` : chatWith;
+}
+/** What the studio server answered, or what it said went wrong. */
+async function answered(response) {
+    const body = await response.json().catch(() => undefined);
+    if (response.ok)
+        return body;
+    const said = isRecord(body) && typeof body.message === 'string' ? body.message : undefined;
+    throw new Error(said ?? `The studio server answered ${String(response.status)}.`);
+}
+/** The people already in `place` that the setup file offers. */
+export async function listPeople(project, place) {
+    const body = await answered(await fetch(`${project.endpoint}/people?place=${encodeURIComponent(place)}`));
+    const people = isRecord(body) && Array.isArray(body.people) ? body.people : [];
+    return people.map((person) => readPerson(person, 'existing'));
+}
+/** A new person the setup file makes in `place`. */
+export async function freshPerson(project, place) {
+    const body = await answered(await fetch(`${project.endpoint}/people/fresh`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ place }),
+    }));
+    return readPerson(isRecord(body) ? body.person : undefined, 'fresh');
+}