@crewlethq/ui 0.60.0 → 0.62.0

package/README.md

@@ -205,6 +205,14 @@ places:
 - A surface that pans or zooms dispatches `LAYER_REPOSITION_EVENT` on its host
   when the content beneath it moves, and every panel anchored inside follows.
 
+## Changes in 0.62.0
+
+**`ValueField`, a labelled value with the control its kind needs.** `FormField` with the control and the rules every form holding configuration values otherwise rewrites, in one component (`ValueField`, `ValueFieldKind`, `ValueFieldChoice`, `ValueFieldLabels`, `ValueFieldProps`). `kind` picks the control: `text`, `id`, `email` and `url` are a text field, `secret` a password field, `multiline` a `Textarea`, and `choice` and `handle` the `Select` listbox. A `secret` is masked unless its value is exactly one `${NAME}` reference, which reads as a name in the `reference` appearance. Typing `$` in a one-line field offers the names in `references`, ranked closest first and written in as a whole `${NAME}` (`onReferencesNeeded` is called as the list opens, so a caller can refresh it). A `url` wears an `https://` `InputAffix`, read as part of the value, which steps aside for `http://` and for a reference. `url`, `id` and `email` drop whitespace; no kind sets `type="email"`, so a reference is never refused by the browser. Required is the unmarked default: `required={false}` says "(optional)", and `markRequired` says "(required)" where it is news. A choice's `hint` is drawn under its option and joins the help line once chosen, and a stored answer the list no longer offers keeps a row of its own. `isReference` replaces the default `${NAME}` grammar, `mark` draws a logo before the label, `helperOnFocus` is passed to `FormField`, and `labels` replaces the list's name ("Secrets") and the choice placeholder ("Choose one").
+
+**The completion helpers are exported with it**: `referenceAt`, `rankReferences`, `completeReference`, `isWholeReference`, `urlSchemeOf`, `REFERENCE_NAME_PATTERN` and the `ReferenceQuery` type, for a field that completes references in a control of its own.
+
+**`Combobox` on a password field is a combobox only while its list is open.** HTML allows no ARIA role on `type="password"`, so a masked field carried an invalid `role="combobox"` (and `aria-autocomplete` and `aria-expanded`) at rest. It now takes those only while it has options to show. Every other field is unchanged.
+
 ## Changes in 0.58.0
 
 **`Spinner` turns at a calm pace, and its arc breathes.** It turned once per `--motion-duration-slow` (300ms), a transition step, so every running mark (a pending `Button`, `RunChip` while it thinks or works, a running step in `StepList`, `StepStateMark`) spun more than three times a second and read as alarm rather than as work. It now turns once a second (`--motion-duration-turn`, linear) while its arc eases between a quarter and three quarters of the ring on a slower cycle (`--motion-duration-sweep`, 1.5s), with soft ends. The stroke is still one 2px border in the current ink at every size (`em`, `xs`, `sm`, `md`); the arc is cut by a mask, so no side of the border is transparent any more. Under reduced motion it stops as before and keeps its open quarter. The arc's length is a registered custom property (`@property --crewlet-spinner-arc`); a browser without `@property` support steps between the two lengths rather than easing.

package/dist/Combobox/index.js

@@ -1,4 +1,4 @@
-export { Combobox } from '../chunk-VC2M2E7N.js';
+export { Combobox } from '../chunk-PK2P2QH6.js';
 import '../chunk-7KHM2FZH.js';
 import '../chunk-TLIJG4TP.js';
 import '../chunk-PGCLHYVP.js';

package/dist/PrincipalPicker/index.js

@@ -1,5 +1,5 @@
-export { PrincipalPicker } from '../chunk-RPHQNXE5.js';
-import '../chunk-VC2M2E7N.js';
+export { PrincipalPicker } from '../chunk-IOZFPFQS.js';
+import '../chunk-PK2P2QH6.js';
 import '../chunk-7KHM2FZH.js';
 import '../chunk-CI3VPIJN.js';
 import '../chunk-5AQBPHZD.js';

package/dist/Prose/Prose.d.ts

@@ -5,8 +5,11 @@ export interface ProseProps extends HTMLAttributes<HTMLElement> {
     as?: ElementType | undefined;
     tone?: ProseTone | undefined;
     /**
-     * The text is still arriving. It draws a caret after the last character, and
-     * the caret holds still under a reduced-motion preference.
+     * The text is still arriving. It draws a caret at the end of the last line
+     * of text (after the last paragraph or heading of rendered Markdown, and
+     * none on an empty block), and the caret holds still under a reduced-motion
+     * preference. A chat answer draws `ThinkingIndicator` after its prose
+     * instead, which never sits inside the words.
      */
     streaming?: boolean | undefined;
     /**

package/dist/Prose/index.js

@@ -1,2 +1,2 @@
-export { Prose } from '../chunk-JCSA3XVH.js';
+export { Prose } from '../chunk-DVVP27OD.js';
 import '../chunk-ODEQTPFM.js';

package/dist/{Prose-BTXNFT2Q.css → Prose-OMV2T6NT.css}

@@ -61,7 +61,23 @@
   transition: color var(--motion-duration-slow) var(--motion-easing-default);
 }
 
-.crewlet-prose--streaming::after {
+/*
+ * THE CARET ENDS THE LAST LINE OF TEXT, never a line of its own. On a block
+ * that holds rendered Markdown, the block's own ::after came after its last
+ * paragraph or list, so the caret stood alone on a new line; and on a reply
+ * with no words yet it stood alone at the start. So: no caret on an empty
+ * block, none on the block itself when its children are blocks, and the caret
+ * after the last child instead when that child is a paragraph or a heading,
+ * whose last line it then ends. A list, a table or code last draws none: a
+ * caret after its final row reads as a stray mark, not as the end of a line.
+ */
+.crewlet-prose--streaming:empty::after,
+.crewlet-prose--streaming:has(> :is(p, div, ul, ol, pre, table, blockquote, h1, h2, h3, h4, h5, h6))::after {
+  content: none;
+}
+
+.crewlet-prose--streaming::after,
+.crewlet-prose--streaming > :is(p, h1, h2, h3, h4, h5, h6):last-child::after {
   content: '';
   display: inline-block;
   width: 2px;
@@ -93,7 +109,8 @@
     transition: none;
   }
 
-  .crewlet-prose--streaming::after {
+  .crewlet-prose--streaming::after,
+  .crewlet-prose--streaming > :is(p, h1, h2, h3, h4, h5, h6):last-child::after {
     animation: none;
   }
 }

package/dist/RichEditor/index.js

@@ -1,4 +1,4 @@
-export { RichEditor, preloadRichEditor } from '../chunk-V57TGM2L.js';
+export { RichEditor, preloadRichEditor } from '../chunk-5MN2HISF.js';
 export { RICH_EDITOR_LABELS, richEditorLabels } from '../chunk-CSQTDGTS.js';
 import '../chunk-BAKPMH3S.js';
 import '../chunk-BPCY7ZID.js';

package/dist/SendButton/SendButton.d.ts

@@ -2,9 +2,9 @@ import { type IconButtonProps } from '../IconButton/index.js';
 /** Whether the button sends the message or stops the request already running. */
 export type SendButtonMode = 'send' | 'stop';
 export interface SendButtonLabels {
-    /** The send button's name and tooltip. */
+    /** The send button's name. */
     send: string;
-    /** The stop button's name and tooltip. */
+    /** The stop button's name. */
     stop: string;
 }
 export declare const SEND_BUTTON_LABELS: SendButtonLabels;
@@ -14,10 +14,14 @@ export interface SendButtonProps extends Omit<IconButtonProps, 'label' | 'icon'
     /** Called on a press in either mode: the caller sends, or stops what is running. */
     onPress: () => void;
     /**
-     * Why it cannot send right now ("Write a question first", "Offline"). Soft
-     * disabled, as every disabled control here is: it keeps its place in the
-     * tab order and says why. Ignored while stopping, because Stop is always
-     * available while something runs.
+     * Why it cannot be pressed right now, in a few words. Soft disabled, as
+     * every disabled control here is: it keeps its place in the tab order, a
+     * screen reader is told the reason, and the pointer's tooltip says it.
+     *
+     * In `send` mode it is why there is nothing to send ("Type a question
+     * first", "Offline"). In `stop` mode it is a stop already under way
+     * ("Stopping"), which a second press could not hurry; leave it out while
+     * the request runs and Stop is always available.
      */
     disabledReason?: string | undefined;
     labels?: Partial<SendButtonLabels> | undefined;
@@ -27,12 +31,22 @@ export interface SendButtonProps extends Omit<IconButtonProps, 'label' | 'icon'
  *
  * ONE ELEMENT IN BOTH MODES, so the button a keyboard reader is on stays
  * focused when the request starts or ends: it changes what it says ("Send",
- * "Stop") and how it looks, never which element it is.
+ * "Stop") and how it looks, never which element it is. Both glyphs are drawn
+ * in one cell and the one not in use is faded and scaled away, so the change
+ * is a short cross fade in place rather than a swap.
+ *
+ * SEND is the accent square with the arrow, the one decision in the composer.
+ * With nothing to send it is not a faded accent, which read as a muddy block
+ * on the dark ground: it is the accent's soft tint with the arrow in the
+ * tertiary ink, and it lights up in the accent the moment there is something
+ * to send.
+ *
+ * STOP is the bordered square with a small filled square in the primary ink,
+ * the mark every media control uses for "stop", and an accent arc travelling
+ * round its edge while the request runs: the button says both that something
+ * is under way and how to end it. Stop is quieter than Send on purpose, a way
+ * out rather than the decision.
  *
- * SEND is the accent square (IconButton `primary`) with the arrow; STOP is the
- * bordered square (IconButton `secondary`) with a filled square in the primary
- * ink. Stop is quieter than Send on purpose: an inverse block was the loudest
- * thing on the panel in dark mode, and Stop is a way out, not the decision.
  * Inside a `Composer`'s `trailing` slot its corner nests in the composer's.
  */
 export declare const SendButton: import("react").ForwardRefExoticComponent<SendButtonProps & import("react").RefAttributes<HTMLButtonElement>>;

package/dist/SendButton/index.d.ts

@@ -1,2 +1,3 @@
+import './SendButton.css';
 export { SEND_BUTTON_LABELS, SendButton } from './SendButton.js';
 export type { SendButtonLabels, SendButtonMode, SendButtonProps } from './SendButton.js';

package/dist/SendButton/index.js

@@ -1,4 +1,4 @@
-export { SEND_BUTTON_LABELS, SendButton } from '../chunk-XN5L5E5D.js';
+export { SEND_BUTTON_LABELS, SendButton } from '../chunk-PBR5C5MX.js';
 import '../chunk-2XWFWNDT.js';
 import '../chunk-UT6CW3C7.js';
 import '../chunk-ODEQTPFM.js';

package/dist/SendButton-L4UX54XS.css

@@ -0,0 +1,173 @@
+/*
+ * A chat composer's Send, which becomes Stop. See SendButton.tsx for what each
+ * state says. The surfaces, edges and hover and press inks are IconButton's
+ * primary and secondary squares; this sheet adds the glyph cross fade, the
+ * quiet held state, the press and the running arc.
+ */
+
+/*
+ * THE ARC'S ANGLE, registered so it can turn. An unregistered custom property
+ * animates in one step at the halfway point, which would make the arc jump
+ * between two places rather than travel.
+ */
+@property --crewlet-send-button-arc {
+  syntax: '<angle>';
+  inherits: false;
+  initial-value: 0deg;
+}
+
+.crewlet-send-button {
+  position: relative;
+  transition:
+    background var(--motion-duration-fast) var(--motion-easing-default),
+    border-color var(--motion-duration-fast) var(--motion-easing-default),
+    color var(--motion-duration-fast) var(--motion-easing-default),
+    transform var(--motion-duration-instant) var(--motion-easing-out);
+}
+
+/* A press sinks the square a little, so the pointer feels it land. */
+.crewlet-send-button:active:not([aria-disabled='true']) {
+  transform: scale(0.94);
+}
+
+/*
+ * BOTH GLYPHS IN ONE CELL. The one in use stands at full size; the other is
+ * faded and scaled to half, and the two trade places on the base step with
+ * the entering surface's ease, so Send turning into Stop reads as one control
+ * changing its mind rather than as two buttons swapping.
+ */
+.crewlet-send-button__glyphs {
+  display: grid;
+  place-items: center;
+}
+
+.crewlet-send-button__glyph {
+  grid-area: 1 / 1;
+  transition:
+    opacity var(--motion-duration-base) var(--motion-easing-default),
+    transform var(--motion-duration-base) var(--motion-easing-emphasized);
+}
+
+.crewlet-send-button--send .crewlet-send-button__glyph--stop,
+.crewlet-send-button--stop .crewlet-send-button__glyph--send {
+  opacity: 0;
+  transform: scale(0.5);
+}
+
+/*
+ * THE STOP SQUARE IS SMALLER THAN THE ARROW: a filled block at the arrow's
+ * 14px was the heaviest mark on the panel. At the 12px step its square is
+ * nine pixels, crisp on the pixel grid and the weight of the arrow's stroke.
+ */
+.crewlet-send-button.crewlet-icon-btn--md .crewlet-send-button__glyph--stop {
+  width: var(--font-size-xs);
+  height: var(--font-size-xs);
+}
+
+/*
+ * HELD, AT FULL OPACITY, with the glyph in the tertiary ink. A faded accent
+ * block read as a muddy, broken button on the dark ground, and the composer's
+ * own fade multiplied it further. Send held is the accent's soft tint, so it
+ * is still the purple control that lights up the moment there is something
+ * to send; Stop held (a stop already under way) is the neutral hover overlay,
+ * since nothing about it is waiting to light up.
+ */
+.crewlet-send-button.crewlet-icon-btn[aria-disabled='true'] {
+  opacity: 1;
+  border-color: transparent;
+  color: var(--color-text-tertiary);
+}
+
+.crewlet-send-button--send.crewlet-icon-btn[aria-disabled='true'] {
+  background: var(--color-brand-accent-soft);
+}
+
+.crewlet-send-button--stop.crewlet-icon-btn[aria-disabled='true'] {
+  background: var(--color-surface-hover);
+}
+
+/*
+ * THE RUNNING ARC: a band of the accent travelling round Stop's edge, over its
+ * own 1px border, with a tail that fades behind it. The band is a conic
+ * gradient cut to a 2px ring by a mask (a mask reads only alpha, so its black
+ * is opacity rather than a colour), so it follows the rounded corner exactly.
+ * One round is the working ring's sweep period, and it fades in on the
+ * moderate step as Stop arrives.
+ */
+.crewlet-send-button--stop::before {
+  content: '';
+  position: absolute;
+  inset: -1px;
+  padding: 2px;
+  border-radius: inherit;
+  background: conic-gradient(
+    from var(--crewlet-send-button-arc),
+    transparent 0turn,
+    transparent 0.55turn,
+    var(--color-brand-accent) 1turn
+  );
+  -webkit-mask:
+    linear-gradient(#000 0 0) content-box,
+    linear-gradient(#000 0 0);
+  -webkit-mask-composite: xor;
+  mask:
+    linear-gradient(#000 0 0) content-box exclude,
+    linear-gradient(#000 0 0);
+  /* Paint, never a target. */
+  pointer-events: none;
+  animation:
+    crewlet-send-button-arc var(--motion-duration-sweep) linear infinite,
+    crewlet-send-button-arc-in var(--motion-duration-moderate) var(--motion-easing-out);
+}
+
+/* A stop already under way has nothing left to show running. */
+.crewlet-send-button--stop[aria-disabled='true']::before {
+  display: none;
+}
+
+@keyframes crewlet-send-button-arc {
+  to {
+    --crewlet-send-button-arc: 360deg;
+  }
+}
+
+@keyframes crewlet-send-button-arc-in {
+  from {
+    opacity: 0;
+  }
+
+  to {
+    opacity: 1;
+  }
+}
+
+/*
+ * UNDER REDUCED MOTION nothing travels or scales: the glyphs change in place,
+ * and the arc becomes the whole edge in the accent, still and still saying
+ * that something runs.
+ */
+@media (prefers-reduced-motion: reduce) {
+  .crewlet-send-button {
+    transition: none;
+  }
+
+  .crewlet-send-button:active:not([aria-disabled='true']) {
+    transform: none;
+  }
+
+  .crewlet-send-button__glyph {
+    transition: none;
+  }
+
+  .crewlet-send-button--stop::before {
+    background: var(--color-brand-accent);
+    animation: none;
+  }
+}
+
+/* The system draws its own edge; a masked gradient is not repainted there. */
+@media (forced-colors: active) {
+  .crewlet-send-button--stop::before {
+    display: none;
+  }
+}

package/dist/ThinkingIndicator/ThinkingIndicator.d.ts

@@ -0,0 +1,37 @@
+import type { HTMLAttributes } from 'react';
+export interface ThinkingIndicatorProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /**
+     * What the assistant is doing now, beside the mark, under a slow shimmer:
+     * "Thinking", then the step that runs ("Listing the agents"). Left out, the
+     * mark stands alone, as it does while an answer's words arrive.
+     */
+    status?: string | undefined;
+    /**
+     * What a screen reader is told, once, when the indicator appears.
+     * "Thinking" by default. It never changes with `status`, so a reader is not
+     * told every step the assistant takes while they read.
+     */
+    label?: string | undefined;
+}
+/**
+ * The assistant at work, drawn where its answer will be: the Assistant's mark
+ * with its four blades turning a quarter at a time around a still core, and,
+ * while nothing of the answer is on screen yet, a line saying what it is doing
+ * under a slow shimmer.
+ *
+ * IN PLACE OF A CARET. A blinking bar after streamed text lands wherever the
+ * last block ends, on a line of its own under a list or at the start of an
+ * empty reply. The mark is a block of its own after the answer, one line of
+ * prose tall, so it never sits inside the words, and nothing moves when the
+ * first of them arrive: they are written above it, and it keeps its height.
+ *
+ * ONE ANNOUNCEMENT. `label` is said once, through a status region that keeps
+ * the same words for as long as the indicator stands; the visible line, which
+ * changes with every step, is hidden from assistive technology, where the
+ * steps are read from their own list.
+ *
+ * UNDER REDUCED MOTION the blades hold still and the line is drawn in the
+ * secondary ink without the shimmer: the mark and the words still say that
+ * work is under way.
+ */
+export declare function ThinkingIndicator({ status, label, className, ...rest }: ThinkingIndicatorProps): import("react").JSX.Element;

package/dist/ThinkingIndicator/index.d.ts

@@ -0,0 +1,3 @@
+import './ThinkingIndicator.css';
+export { ThinkingIndicator } from './ThinkingIndicator.js';
+export type { ThinkingIndicatorProps } from './ThinkingIndicator.js';

package/dist/ThinkingIndicator/index.js

@@ -0,0 +1,3 @@
+export { ThinkingIndicator } from '../chunk-E2MIUNUU.js';
+import '../chunk-UT6CW3C7.js';
+import '../chunk-ODEQTPFM.js';

package/dist/ThinkingIndicator-QJMX2TXC.css

@@ -0,0 +1,122 @@
+/*
+ * The assistant at work: the Assistant's mark, its blades turning, and a line
+ * of status under a shimmer. See ThinkingIndicator.tsx for why it replaces a
+ * caret and how it is announced.
+ */
+
+/*
+ * ONE LINE OF PROSE TALL, at every state: the mark alone, the mark with a
+ * status line, and the line changing from one step to the next all keep the
+ * same height, so the thread never moves while the assistant works.
+ */
+.crewlet-thinking {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-2);
+  min-width: 0;
+  min-height: calc(var(--font-size-compact) * var(--font-line-height-relaxed));
+  font-family: var(--font-family-sans);
+  font-size: var(--font-size-compact);
+  line-height: var(--font-line-height-relaxed);
+}
+
+/*
+ * THE BLADES TURN A QUARTER, THEN REST. The figure is four blades around a
+ * core, the same after a quarter turn, so each round ends where the next
+ * begins and the loop never shows a seam. One round is the breath period
+ * (2.2s): the turn takes its first half on the in-out ease and the second
+ * half is still, which reads as steady thought rather than as a spinner. The
+ * core holds still, as the mark's own description promises.
+ */
+.crewlet-thinking__mark [data-motion='turn'] {
+  transform-box: view-box;
+  transform-origin: 50% 50%;
+  animation: crewlet-thinking-turn var(--motion-duration-breath) var(--motion-easing-in-out) infinite;
+}
+
+@keyframes crewlet-thinking-turn {
+  0% {
+    transform: rotate(0deg);
+  }
+
+  50%,
+  100% {
+    transform: rotate(90deg);
+  }
+}
+
+/*
+ * THE SHIMMER IS A LIGHTER BAND CROSSING THE WORDS, the band Skeleton sweeps
+ * across a placeholder, set in ink rather than in surface: the words are the
+ * secondary ink at rest, so they read at every point of the sweep, and the
+ * band is the primary ink. The gradient is clipped to the glyphs and is three
+ * times the line's width, so the band crosses it rather than standing in it.
+ */
+.crewlet-thinking__status {
+  min-width: 0;
+  overflow: hidden;
+  color: var(--color-text-secondary);
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  animation: crewlet-thinking-enter var(--motion-duration-moderate) var(--motion-easing-out);
+}
+
+@supports (background-clip: text) or (-webkit-background-clip: text) {
+  .crewlet-thinking__status {
+    background-image: linear-gradient(
+      90deg,
+      var(--color-text-secondary) 0%,
+      var(--color-text-secondary) 40%,
+      var(--color-text-primary) 50%,
+      var(--color-text-secondary) 60%,
+      var(--color-text-secondary) 100%
+    );
+    background-size: 300% 100%;
+    -webkit-background-clip: text;
+    background-clip: text;
+    color: transparent;
+    animation:
+      crewlet-thinking-enter var(--motion-duration-moderate) var(--motion-easing-out),
+      crewlet-thinking-shimmer var(--motion-duration-breath) linear infinite;
+  }
+}
+
+@keyframes crewlet-thinking-shimmer {
+  from {
+    background-position: 100% 50%;
+  }
+
+  to {
+    background-position: 0 50%;
+  }
+}
+
+@keyframes crewlet-thinking-enter {
+  from {
+    opacity: 0;
+  }
+
+  to {
+    opacity: 1;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .crewlet-thinking__mark [data-motion='turn'] {
+    animation: none;
+  }
+
+  .crewlet-thinking__status {
+    background-image: none;
+    color: var(--color-text-secondary);
+    animation: none;
+  }
+}
+
+/* The system's own ink: a gradient clipped to text is dropped there. */
+@media (forced-colors: active) {
+  .crewlet-thinking__status {
+    background-image: none;
+    color: CanvasText;
+  }
+}

package/dist/ValueField/ValueField.d.ts

@@ -0,0 +1,117 @@
+import { type ReactNode } from 'react';
+/**
+ * What a value field holds, which decides its control and what it does to a
+ * value on its way through.
+ *
+ * - `text`: free text, spaces kept.
+ * - `multiline`: prose in a textarea, every space and newline kept, spell check on.
+ * - `secret`: a credential, masked unless the value is a whole reference.
+ * - `url`: an address, wearing an `https://` affix, whitespace dropped.
+ * - `id` and `email`: one token, whitespace dropped.
+ * - `choice` and `handle`: one of `choices`, picked from a listbox.
+ */
+export type ValueFieldKind = 'text' | 'multiline' | 'secret' | 'url' | 'id' | 'choice' | 'handle' | 'email';
+/** One option of a `choice` or `handle` field. */
+export interface ValueFieldChoice {
+    value: string;
+    label: string;
+    /** A sentence saying what picking this one does: drawn under the option, and on the help line once chosen. */
+    hint?: string | undefined;
+}
+/** The words a value field draws itself. */
+export interface ValueFieldLabels {
+    /** Names the completion list. "Secrets" by default. */
+    references: string;
+    /** The choice placeholder while nothing is chosen. "Choose one" by default. */
+    choose: string;
+}
+export interface ValueFieldProps {
+    label: string;
+    /** A mark drawn before the label, such as a third party's own logo. */
+    mark?: ReactNode;
+    kind?: ValueFieldKind | undefined;
+    value: string;
+    onChange: (value: string) => void;
+    /** Where the value comes from, or what shape it takes. */
+    help?: ReactNode;
+    /** Why the last value was refused. */
+    error?: ReactNode;
+    placeholder?: string | undefined;
+    /** What a `choice` or `handle` field offers; ignored by every other kind. */
+    choices?: readonly ValueFieldChoice[] | undefined;
+    disabled?: boolean | undefined;
+    /**
+     * Whether an answer is required. REQUIRED IS THE UNMARKED DEFAULT: `false`
+     * says "(optional)" beside the label, `true` sets `aria-required` and draws
+     * nothing unless `markRequired` says the requiredness is news. Most fields
+     * on a form are required, and marking them all is noise that teaches a
+     * reader to skip the note.
+     */
+    required?: boolean | undefined;
+    /**
+     * Says "(required)" beside the label, for a field whose requiredness is
+     * NEWS: one that appeared because of an answer above it. Read only with
+     * `required`.
+     */
+    markRequired?: boolean | undefined;
+    autoFocus?: boolean | undefined;
+    /**
+     * The stored entry names offered when somebody types `$`, completed into a
+     * whole `${NAME}`. NAMES ONLY: a value never reaches the field, so a list
+     * that could not be assembled leaves the field exactly as it was.
+     */
+    references?: readonly string[] | undefined;
+    /**
+     * Called as the completion list is about to open, so the caller can make
+     * sure the names are current. On the way in only, never per keystroke.
+     */
+    onReferencesNeeded?: (() => void) | undefined;
+    /**
+     * Whether a value is exactly one reference, which keeps a `secret` field
+     * readable and lets a `url` field's affix step aside. [isWholeReference]
+     * by default; a product with its own reference grammar passes it here.
+     */
+    isReference?: ((value: string) => boolean) | undefined;
+    /** How many lines a `multiline` field shows before it scrolls. Three by default. */
+    rows?: number | undefined;
+    /** Show the help line only while the field has focus. See [FormField]. */
+    helperOnFocus?: boolean | undefined;
+    labels?: Partial<ValueFieldLabels> | undefined;
+    className?: string | undefined;
+}
+/**
+ * A labelled value: [FormField] with the control a kind of value needs, and
+ * the rules every form holding such values otherwise rewrites.
+ *
+ * A SECRET FIELD IS A PASSWORD FIELD, and that is not decoration: `type` is
+ * what keeps the value out of an autofill store, out of a screenshot and out
+ * of the accessibility tree as text.
+ *
+ * A REFERENCE IS NOT A CREDENTIAL, so it is not masked. A secret whose value
+ * is wholly a `${NAME}` holds the NAME of a stored entry, and the reader has
+ * to be able to see which entry it points at. Typing over it masks again the
+ * moment it stops being a whole reference, so a credential is never on screen.
+ *
+ * TYPING `$` OFFERS THE STORED ENTRIES, from `references`, ranked closest
+ * first and written in as a whole `${NAME}` with the caret after it. Tab and
+ * Enter take the highlighted name, Escape closes the list and keeps what was
+ * typed, and a press outside closes only the list.
+ *
+ * A URL FIELD WEARS ITS SCHEME. An `https://` affix sits inside the box, is
+ * read once as part of the value, and is written into it. It steps aside for
+ * a value that carries `http://` and for one starting with `$` (a reference
+ * carries its own scheme once it resolves), and a pasted `https://` is not
+ * doubled onto it.
+ *
+ * A SINGLE TOKEN TAKES NO WHITESPACE. A `url`, `id` or `email` drops it as it
+ * is typed or pasted: a space around one is invisible in the box and fatal
+ * wherever it is used. No field asserts `type="email"`, because the browser
+ * would refuse a reference for having no "@" in it; `inputMode` still offers
+ * the right keyboard.
+ *
+ * A CHOICE IS THE LISTBOX, which can draw each choice's hint under it. The
+ * chosen one's hint also joins the help line, and a stored answer the list
+ * no longer offers keeps a row of its own rather than vanishing into a
+ * different selection.
+ */
+export declare function ValueField({ label, mark, kind, value, onChange, help, error, placeholder, choices, disabled, required, markRequired, autoFocus, references, onReferencesNeeded, isReference, rows, helperOnFocus, labels, className, }: ValueFieldProps): import("react").JSX.Element;

package/dist/ValueField/index.d.ts

@@ -0,0 +1,10 @@
+import '../Input/Input.css';
+import '../VisuallyHidden/VisuallyHidden.css';
+import '../HitArea/HitArea.css';
+import '../Combobox/Combobox.css';
+import '../Select/Select.css';
+import './ValueField.css';
+export { ValueField } from './ValueField.js';
+export type { ValueFieldChoice, ValueFieldKind, ValueFieldLabels, ValueFieldProps } from './ValueField.js';
+export { REFERENCE_NAME_PATTERN, completeReference, isWholeReference, rankReferences, referenceAt, urlSchemeOf, } from './references.js';
+export type { ReferenceQuery } from './references.js';

package/dist/ValueField/index.js

@@ -0,0 +1,15 @@
+export { REFERENCE_NAME_PATTERN, ValueField, completeReference, isWholeReference, rankReferences, referenceAt, urlSchemeOf } from '../chunk-OD3Z6QKN.js';
+import '../chunk-XQZ6EWOE.js';
+import '../chunk-PK2P2QH6.js';
+import '../chunk-7KHM2FZH.js';
+import '../chunk-TLIJG4TP.js';
+import '../chunk-PGCLHYVP.js';
+import '../chunk-PQADV6P6.js';
+import '../chunk-2G355KDJ.js';
+import '../chunk-OMV5W53A.js';
+import '../chunk-2YTOOH3A.js';
+import '../chunk-H5XTJ7GJ.js';
+import '../chunk-2XWFWNDT.js';
+import '../chunk-NUZHC6MM.js';
+import '../chunk-UT6CW3C7.js';
+import '../chunk-ODEQTPFM.js';