@mythicalos/preact-ui 0.2.2 → 0.4.0

package/README.md

@@ -34,6 +34,7 @@ import "@mythicalos/ui-core/styles.css"; // this package ships NO CSS of its own
 
 - `Button` — 5 variants × 6 states, loading spinner, inert+aria-busy.
 - `Input`, `Toggle`, `Checkbox` — inputs with the "unconfigured is a valid state" neutral empty.
+  `<Input type="password" revealable>` adds a show/hide toggle inside the field (see below).
 - `MaskedSecretInput` — presence-only secret slots; the value never round-trips to the UI.
 - `EmptyState` — the designed empty moments (spine motif; never an error tone).
 - `ConfirmDialog` (+ `typedNameMatches`), `Scrim` — modal danger confirms (Esc cancels, safe action
@@ -51,11 +52,45 @@ import "@mythicalos/ui-core/styles.css"; // this package ships NO CSS of its own
   `statusLineClass`, `bannerClass`, `BANNER_ICON`, `gaugeTone`, `gaugeGeom`, `nextPollDelay`,
   `makePollEpochGuard`, `runPollTick`, `POLL_JITTER_RATIO`, `POLL_BACKOFF_CAP_MS`.
 
+## `revealable` — the show/hide affordance for a secret field (0.3.0)
+
+```tsx
+<Input label="UI token" type="password" revealable mono placeholder="paste your token…" />
+```
+
+Opt-in and inert everywhere else: without `revealable`, or on any type other than `password`, the
+markup is byte-identical to what this component rendered before the prop existed. When it is on:
+
+- the field starts **hidden** — revealing is always an explicit act, and no consumer can force it
+  open (the state is held inside the component);
+- the toggle is a real `<button type="button">` in normal tab order, no `tabindex`, with
+  `aria-pressed` for the state and an `aria-label` for the action (`Show token` / `Hide token`);
+- revealing swaps only the input's own `type`; the value is never copied into any other node,
+  attribute or `aria-*` string;
+- the field carries `autocomplete="new-password"`, not the atom's usual `off` — browsers largely
+  ignore `off` on a password field and will autofill it and offer to save it as a login;
+- the component never takes an id from preact's shared `useId` sequence, so installing this
+  version cannot renumber the ids of anything else in your tree;
+- `revealLabels={{ show, hide }}` renames the toggle for a field that is not a token (the default
+  wording is `Show token` / `Hide token`);
+- because a `<button>` may not sit inside a `<label>`, this path pairs label and control by
+  `for`/`id` instead of wrapping (an `id` is generated if you don't pass one);
+- flipping `revealable` or `type` re-renders the field, it does not remount it — a focused input
+  keeps its focus, caret and selection — and any such flip returns the field to hidden, so a
+  secret revealed before the flip is never in the clear after it;
+- the generated id is namespaced (`mythicalos-input-N`). It is only ever used to pair this
+  field's own label with its own input, so both sides always agree; pass `id` yourself if you
+  server-render and want a specific one.
+
+Requires `@mythicalos/ui-core` **≥ 0.2.0** for the toggle's styles (`.input-reveal`,
+`.input-reveal__btn`).
+
 ## Styles
 
 This package ships **no stylesheet**. Serve `@mythicalos/ui-core/styles.css` (after
 `@mythicalos/tokens`) — it carries every class this package's components emit, including the 7 new
-atoms (`.my-chip`, `.my-status`, `.my-card`, `.my-avatar`, `.my-search`, `.my-banner`, `.my-gauge`).
+atoms (`.my-chip`, `.my-status`, `.my-card`, `.my-avatar`, `.my-search`, `.my-banner`, `.my-gauge`)
+and the reveal affordance (`.input-reveal`).
 
 ## Provenance
 

package/dist/FileExplorer.d.ts

@@ -0,0 +1,75 @@
+/** @jsxImportSource preact */
+import type { ComponentChildren } from "preact";
+import { breadcrumbSegments, buildBreadcrumb, countFileRows, countLoadedFiles, deriveFileTreeRows, formatFileSize, formatRelativeTime, previewBodyMode, previewMeta, type DirState, type FilePreviewState, type FileScopeOption, type FileTreeMode, type FileTreeRootSpec, type FileTreeRow, type GitMark, type PreviewBadgeState } from "@mythicalos/ui-core/logic";
+export { breadcrumbSegments, buildBreadcrumb, countFileRows, countLoadedFiles, deriveFileTreeRows, formatFileSize, formatRelativeTime, previewBodyMode, previewMeta, type DirState, type FilePreviewState, type FileScopeOption, type FileTreeMode, type FileTreeRootSpec, type FileTreeRow, type GitMark, type PreviewBadgeState, };
+export interface FileScopePickerProps {
+    /** The offered scopes. With fewer than two the picker renders a STATIC label — there is nothing
+     *  to choose, so no control is offered. */
+    options: readonly FileScopeOption[];
+    activeKey: string;
+    /** The active scope's tree mode — drives the trigger glyph (⌂ all-mounts · ◈ project). */
+    mode: FileTreeMode;
+    open: boolean;
+    onToggle?: (next: boolean) => void;
+    onSelect?: (key: string) => void;
+    /** Fired on Escape so the caller can close AND restore focus to wherever it wants it. */
+    onDismiss?: () => void;
+    label?: string;
+}
+/**
+ * A plain disclosure of buttons — deliberately NOT an ARIA menu/listbox: those roles promise
+ * arrow-key behavior this does not implement, and claiming them would be a lie to a screen reader.
+ * Each option is a natively Tab/Enter-operable button.
+ */
+export declare function FileScopePicker(props: FileScopePickerProps): import("preact").JSX.Element;
+export interface FileTreeProps {
+    mode: FileTreeMode;
+    roots: readonly FileTreeRootSpec[];
+    /** Every known directory listing, keyed by `nodeId(rootKey, relPath)`. An absent key reads as
+     *  "not fetched yet" and draws a Loading… row, never an empty one. */
+    dirs: Readonly<Record<string, DirState>>;
+    expanded: ReadonlySet<string>;
+    selectedId?: string | null;
+    /** Git marks keyed by node id. An absent entry renders NO mark — never a fabricated clean. */
+    marks?: Readonly<Record<string, GitMark>>;
+    title?: string;
+    /** The header count. Defaults to the honest count of files actually listed so far. */
+    count?: number;
+    branch?: string;
+    /** The scope picker (or anything else) for the rail header. */
+    scope?: ComponentChildren;
+    onToggleDir?: (node: {
+        rootKey: string;
+        relPath: string;
+        id: string;
+    }) => void;
+    onSelectFile?: (node: {
+        rootKey: string;
+        relPath: string;
+        id: string;
+        name: string;
+    }) => void;
+    class?: string;
+}
+export declare function FileTree(props: FileTreeProps): import("preact").JSX.Element;
+export interface FilePreviewProps {
+    /** The previewed file's name. Render this component only when a file IS selected; the
+     *  no-selection placeholder belongs to the page, not to the component. */
+    name: string;
+    /** The breadcrumb head — the card: the breadcrumb ALWAYS includes the root. */
+    rootLabel: string;
+    relPath: string;
+    state: FilePreviewState;
+    /** The header pill. `null` (the default) renders NO pill — never a fabricated "unchanged". */
+    badge?: PreviewBadgeState;
+    /** Listing-derived fallbacks for the header, used where the state carries none. */
+    bytes?: number;
+    mtime?: number;
+    /** Injected for deterministic relative times. */
+    now?: number;
+    /** Renders markdown to nodes. Absent ⇒ a `.md` file falls back to plain mono text rather than
+     *  this component inventing a renderer (or, worse, injecting raw HTML). */
+    renderMarkdown?: (text: string) => ComponentChildren;
+    class?: string;
+}
+export declare function FilePreview(props: FilePreviewProps): import("preact").JSX.Element;

package/dist/FileExplorer.js

@@ -0,0 +1,59 @@
+import { jsx as _jsx, jsxs as _jsxs } from "preact/jsx-runtime";
+import { badgeClass, breadcrumbSegments, buildBreadcrumb, countFileRows, countLoadedFiles, deriveFileTreeRows, formatFileSize, formatRelativeTime, gitMarkClass, gitMarkLabel, previewBadge, previewBadgeClass, previewBodyMode, previewMeta, previewNoteClass, previewNoteText, scopeGlyph, SCOPE_CARET, scopeItemClass, } from "@mythicalos/ui-core/logic";
+export { breadcrumbSegments, buildBreadcrumb, countFileRows, countLoadedFiles, deriveFileTreeRows, formatFileSize, formatRelativeTime, previewBodyMode, previewMeta, };
+/**
+ * A plain disclosure of buttons — deliberately NOT an ARIA menu/listbox: those roles promise
+ * arrow-key behavior this does not implement, and claiming them would be a lie to a screen reader.
+ * Each option is a natively Tab/Enter-operable button.
+ */
+export function FileScopePicker(props) {
+    const { options, activeKey, mode, open, onToggle, onSelect, onDismiss, label } = props;
+    const active = options.find((o) => o.key === activeKey);
+    const text = label ?? active?.label ?? "";
+    const glyph = scopeGlyph(mode);
+    const selectable = options.length > 1;
+    return (_jsxs("div", { class: "my-files__scope", onKeyDown: (e) => {
+            if (e.key === "Escape" && open)
+                onDismiss?.();
+        }, children: [selectable ? (_jsxs("button", { type: "button", class: "my-files__scope-btn", "aria-expanded": open, onClick: () => onToggle?.(!open), children: [_jsx("span", { class: "my-files__scope-glyph", "aria-hidden": "true", children: glyph }), _jsx("span", { class: "my-files__scope-label", children: text }), _jsx("span", { class: "my-files__scope-caret", "aria-hidden": "true", children: SCOPE_CARET })] })) : (_jsxs("div", { class: "my-files__scope-static", children: [_jsx("span", { class: "my-files__scope-glyph", "aria-hidden": "true", children: glyph }), _jsx("span", { class: "my-files__scope-label", children: text })] })), open && selectable ? (_jsx("div", { class: "my-files__scope-menu", children: options.map((o) => (_jsxs("div", { children: [_jsxs("button", { type: "button", class: scopeItemClass(o.key === activeKey), "aria-current": o.key === activeKey, onClick: () => onSelect?.(o.key), children: [_jsx("span", { class: "my-files__scope-it-name", children: o.label }), _jsx("span", { class: "my-files__scope-it-count", children: o.count })] }), o.dividerAfter === true ? _jsx("div", { class: "my-files__scope-divider", "aria-hidden": "true" }) : null] }, o.key))) })) : null] }));
+}
+export function FileTree(props) {
+    const { mode, roots, dirs, expanded, selectedId = null, marks, title = "Files", count, branch, scope, onToggleDir, onSelectFile } = props;
+    const rows = deriveFileTreeRows({ mode, roots, dirs, expanded, selectedId, marks });
+    // the rendered-row count — provably what the operator sees (countLoadedFiles is a
+    // different, cache-wide number; see its doc)
+    const total = count ?? countFileRows(rows);
+    return (_jsxs("div", { class: props.class === undefined ? "my-files__rail" : `my-files__rail ${props.class}`, children: [_jsxs("div", { class: "my-files__hd", children: [_jsxs("div", { class: "my-files__ti", children: [_jsx("span", { children: title }), _jsxs("span", { class: "my-files__count", children: ["\u00B7 ", total] }), branch === undefined ? null : (_jsxs("span", { class: "my-files__branch", children: [_jsx("span", { class: "my-files__branch-dot", "aria-hidden": "true" }), branch] }))] }), scope] }), _jsx("div", { class: "my-files__tree", children: rows.map((row) => renderRow(row, onToggleDir, onSelectFile)) })] }));
+}
+function renderRow(row, onToggleDir, onSelectFile) {
+    if (row.type === "note") {
+        return (_jsx("div", { class: row.className, children: row.text }, row.id));
+    }
+    if (row.type === "dir") {
+        // The WHOLE ROW is the hit target — the chevron is the affordance, not a separate control.
+        return (_jsxs("button", { type: "button", class: row.className, "aria-expanded": row.open, onClick: () => onToggleDir?.({ rootKey: row.rootKey, relPath: row.relPath, id: row.id }), children: [_jsx("span", { class: "my-files__chev", "aria-hidden": "true", children: row.chevron }), _jsx("span", { class: "my-files__glyph", "aria-hidden": "true", children: row.glyph }), _jsx("span", { class: "my-files__name", children: row.name }), row.badges.map((b) => (_jsx("span", { class: badgeClass(b.tone), children: b.text }, b.text)))] }, row.id));
+    }
+    return (_jsxs("button", { type: "button", class: row.className, "aria-current": row.selected, onClick: () => onSelectFile?.({ rootKey: row.rootKey, relPath: row.relPath, id: row.id, name: row.name }), children: [_jsx("span", { class: "my-files__spacer", "aria-hidden": "true" }), _jsx("span", { class: "my-files__fglyph", "aria-hidden": "true", children: row.glyph }), _jsx("span", { class: "my-files__fname", children: row.name }), row.mark === null ? null : (
+            // role="img" so the aria-label IS the accessible name — a bare "M" would otherwise be
+            // announced as the opaque glyph rather than "modified".
+            _jsx("span", { class: gitMarkClass(row.mark), role: "img", title: gitMarkLabel(row.mark), "aria-label": gitMarkLabel(row.mark), children: row.mark }))] }, row.id));
+}
+export function FilePreview(props) {
+    const { name, rootLabel, relPath, state, badge = null, now, renderMarkdown } = props;
+    const meta = previewMeta(state, { bytes: props.bytes, mtime: props.mtime });
+    const pill = previewBadge(badge);
+    return (_jsxs("div", { class: props.class === undefined ? "my-files__prev" : `my-files__prev ${props.class}`, children: [_jsxs("div", { class: "my-files__prev-hd", children: [_jsxs("div", { class: "my-files__prev-main", children: [_jsx("div", { class: "my-files__crumb", children: buildBreadcrumb(rootLabel, relPath) }), _jsxs("div", { class: "my-files__name-row", children: [_jsx("b", { class: "my-files__prev-name", children: name }), pill === null ? null : _jsx("span", { class: previewBadgeClass(pill.tone), children: pill.text })] })] }), _jsxs("div", { class: "my-files__meta", children: [meta.bytes === undefined ? null : _jsx("span", { children: formatFileSize(meta.bytes) }), meta.mtime === undefined ? null : _jsxs("span", { children: ["modified ", formatRelativeTime(meta.mtime, now)] })] })] }), _jsx("div", { class: "my-files__prev-bd", children: previewBody(name, state, renderMarkdown) })] }));
+}
+/** The body for the current state. Every non-`text` branch is a note — including all four honest
+ *  states, each with its own distinct class and none styled as a failure. */
+function previewBody(name, state, renderMarkdown) {
+    // ONE decision, made in ui-core — this binding never re-derives it.
+    const mode = previewBodyMode(name, state, renderMarkdown !== undefined);
+    if (mode === "note")
+        return _jsx("div", { class: previewNoteClass(state) ?? "", children: previewNoteText(state) });
+    // "note" covers every non-text state, so the text branch is what remains
+    const text = state.text;
+    if (mode === "markdown")
+        return _jsx("div", { class: "my-files__md", children: renderMarkdown(text) });
+    return _jsx("pre", { class: "my-files__pre", children: text });
+}

package/dist/GitChip.d.ts

@@ -0,0 +1,18 @@
+/** @jsxImportSource preact */
+import { GIT_BRANCH_GLYPH, GIT_BRANCH_UNKNOWN, GIT_CHIP_PARTS, GIT_CLEAN_LABEL, GIT_DETACHED_LABEL, GIT_LOADING_NOTE, GIT_STALE_LABEL, GIT_STALE_TITLE, GIT_UNAVAILABLE_NOTE, gitBranchLabel, gitChipClass, gitChipNote, gitFlagClass, gitFlags, hasGitStatus, type GitFlag, type GitFlagTone, type GitStatus } from "@mythicalos/ui-core/logic";
+export { gitBranchLabel, gitChipClass, gitChipNote, gitFlagClass, gitFlags, hasGitStatus, GIT_BRANCH_GLYPH, GIT_BRANCH_UNKNOWN, GIT_CHIP_PARTS, GIT_CLEAN_LABEL, GIT_DETACHED_LABEL, GIT_LOADING_NOTE, GIT_STALE_LABEL, GIT_STALE_TITLE, GIT_UNAVAILABLE_NOTE, type GitFlag, type GitFlagTone, type GitStatus, };
+export interface GitChipProps {
+    /** The reported status. Absent — `undefined` OR `null`, so a "no data yet" slot can be passed
+     *  straight through — ⇒ the honest unavailable arm, never a fabricated clean tree. */
+    status?: GitStatus | null;
+    /** Human copy for why there is no status. The product maps its own reason codes to this
+     *  sentence; the atom carries no reason vocabulary of its own. */
+    unavailableNote?: string;
+    /** The first read has not returned yet — only used when there is no `status` and no note. */
+    loading?: boolean;
+    /** The shown status is RETAINED while the live read is failing: stale, not current. Flagged on
+     *  both arms. */
+    stale?: boolean;
+    class?: string;
+}
+export declare function GitChip(props: GitChipProps): import("preact").JSX.Element;

package/dist/GitChip.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx, jsxs as _jsxs } from "preact/jsx-runtime";
+/** @jsxImportSource preact */
+// @mythicalos/preact-ui — the git status chip (ds/components-git-chip.html): a bordered inline
+// mono chip carrying `⎇ <branch>` and honest counter flags (warn-soft behind/uncommitted,
+// error-soft unpushed, ok-soft clean).
+//
+// Extracted from the reference implementation in the reference product's session detail pane. Its
+// `available:false` reason ENUM and copy table were one daemon's wire vocabulary; here the product
+// maps its own reason to a sentence and passes it as `unavailableNote`. The honesty contract is
+// design, not product, and is preserved by `@mythicalos/ui-core`'s `gitFlags`/`gitBranchLabel`:
+// an absent status renders the unavailable arm, `null` behind/unpushed OMIT their flag (never
+// "0 behind"), a `null` branch reads "detached HEAD", and a status that never reported its counters
+// is NEVER collapsed into a green "clean ✓".
+import { GIT_BRANCH_GLYPH, GIT_BRANCH_UNKNOWN, GIT_CHIP_PARTS, GIT_CLEAN_LABEL, GIT_DETACHED_LABEL, GIT_LOADING_NOTE, GIT_STALE_LABEL, GIT_STALE_TITLE, GIT_UNAVAILABLE_NOTE, gitBranchLabel, gitChipClass, gitChipNote, gitFlagClass, gitFlags, hasGitStatus, } from "@mythicalos/ui-core/logic";
+export { gitBranchLabel, gitChipClass, gitChipNote, gitFlagClass, gitFlags, hasGitStatus, GIT_BRANCH_GLYPH, GIT_BRANCH_UNKNOWN, GIT_CHIP_PARTS, GIT_CLEAN_LABEL, GIT_DETACHED_LABEL, GIT_LOADING_NOTE, GIT_STALE_LABEL, GIT_STALE_TITLE, GIT_UNAVAILABLE_NOTE, };
+export function GitChip(props) {
+    const { status, stale = false, class: cls = "" } = props;
+    const staleMark = stale ? (_jsx("span", { class: GIT_CHIP_PARTS.stale, title: GIT_STALE_TITLE, children: GIT_STALE_LABEL })) : null;
+    if (hasGitStatus(status)) {
+        const flags = gitFlags(status);
+        return (_jsxs("span", { class: `${gitChipClass({ stale })} ${cls}`, children: [_jsxs("span", { class: GIT_CHIP_PARTS.branch, children: [GIT_BRANCH_GLYPH, " ", gitBranchLabel(status.branch)] }), flags.length > 0 ? (_jsx("span", { class: GIT_CHIP_PARTS.flags, children: flags.map((f) => (_jsx("span", { class: gitFlagClass(f.tone), children: f.label }, f.label))) })) : null, staleMark] }));
+    }
+    const note = gitChipNote({ unavailableNote: props.unavailableNote, loading: props.loading });
+    return (_jsxs("span", { class: `${gitChipClass({ unavailable: true, stale })} ${cls}`, children: [_jsxs("span", { class: GIT_CHIP_PARTS.branch, title: note, children: [GIT_BRANCH_GLYPH, " ", GIT_BRANCH_UNKNOWN] }), _jsx("span", { class: GIT_CHIP_PARTS.note, children: note }), staleMark] }));
+}

package/dist/Input.d.ts

@@ -12,9 +12,62 @@ export interface InputProps {
     dirty?: boolean;
     type?: string;
     id?: string;
+    /**
+     * Opt-in show/hide affordance for a secret field. Honored only for `type="password"`; every
+     * other type (and the default, `revealable` absent/false) renders exactly what it always did.
+     * The field starts hidden — revealing is always an explicit act.
+     */
+    revealable?: boolean;
+    /**
+     * Overrides the reveal toggle's accessible name for a field that is not a token — e.g.
+     * `{ show: "Show API key", hide: "Hide API key" }`. Defaults to the token wording.
+     */
+    revealLabels?: RevealLabels;
     onInput?: (value: string) => void;
     onKeyDown?: (e: JSX.TargetedKeyboardEvent<HTMLInputElement>) => void;
 }
+export interface RevealLabels {
+    show: string;
+    hide: string;
+}
+/** The reveal toggle's default accessible name, per state. Exported for the tests + any consumer
+ *  that needs to find the control by name. */
+export declare const REVEAL_SHOW_LABEL = "Show token";
+export declare const REVEAL_HIDE_LABEL = "Hide token";
+export declare const REVEAL_LABELS: RevealLabels;
+export interface RevealToggleProps {
+    /** True while the secret is shown in the clear. */
+    revealed: boolean;
+    disabled?: boolean;
+    labels?: RevealLabels;
+    onToggle: () => void;
+}
+export declare function RevealToggle({ revealed, disabled, labels, onToggle }: RevealToggleProps): JSX.Element;
+export interface InputBodyProps extends InputProps {
+    /** Reveal state, lifted out of `Input` so a DOM-free test can render BOTH states. */
+    revealed: boolean;
+    onToggleReveal: () => void;
+    /** Fallback id for the reveal path's explicit label/control pairing (see below). */
+    autoId: string;
+}
+/**
+ * `Input`'s hook-free body — exactly the markup `Input` renders, with the reveal state passed in
+ * instead of held. Split out for the same reason `SwitcherPanel` is in the shell package: this
+ * codebase's bun:test environment has no DOM, so a state-driven variant can only be reached by
+ * rendering the hook-free piece directly, and the toggle's real `onClick` closure can only be
+ * invoked by calling this as a plain function. Not part of the package's barrel.
+ */
+export declare function InputBody(props: InputBodyProps): JSX.Element;
+/** True when the field is a secret that opted into the reveal affordance. */
+export declare function isRevealMode(props: Pick<InputProps, "revealable" | "type">): boolean;
+/**
+ * The reveal state to render this pass.
+ *
+ * ANY change of the field's mode clears it. A field that stops being a revealable secret and
+ * later becomes one again must come back hidden: the alternative is a password rendered in the
+ * clear that no one asked to see, on a render the user never touched.
+ */
+export declare function resolveRevealed(stored: boolean, storedMode: boolean, mode: boolean): boolean;
 export declare function Input(props: InputProps): JSX.Element;
 export interface ToggleProps {
     on: boolean;

package/dist/Input.js

@@ -1,5 +1,37 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "preact/jsx-runtime";
-export function Input(props) {
+import { useRef, useState } from "preact/hooks";
+/** The reveal toggle's default accessible name, per state. Exported for the tests + any consumer
+ *  that needs to find the control by name. */
+export const REVEAL_SHOW_LABEL = "Show token";
+export const REVEAL_HIDE_LABEL = "Hide token";
+export const REVEAL_LABELS = { show: REVEAL_SHOW_LABEL, hide: REVEAL_HIDE_LABEL };
+/**
+ * The show/hide button `Input` renders inside a `revealable` password field. A real
+ * `<button type="button">` — focusable in source order, no tabindex games — carrying the
+ * state on `aria-pressed` and the action in its `aria-label`. It never receives, holds or
+ * renders the field's value.
+ */
+/** A caller-supplied name, or the default when it is not a usable one. Runtime-checked: this is a
+ *  public prop of a published package, and a blank or missing override would leave the toggle
+ *  named only by its two-letter visible text — or not at all. */
+function revealName(supplied, fallback) {
+    return typeof supplied === "string" && supplied.trim().length > 0 ? supplied : fallback;
+}
+export function RevealToggle({ revealed, disabled, labels, onToggle }) {
+    const names = {
+        show: revealName(labels?.show, REVEAL_SHOW_LABEL),
+        hide: revealName(labels?.hide, REVEAL_HIDE_LABEL),
+    };
+    return (_jsx("button", { type: "button", class: "input-reveal__btn", "aria-label": revealed ? names.hide : names.show, "aria-pressed": revealed ? "true" : "false", disabled: disabled, onClick: disabled ? undefined : onToggle, children: revealed ? "hide" : "show" }));
+}
+/**
+ * `Input`'s hook-free body — exactly the markup `Input` renders, with the reveal state passed in
+ * instead of held. Split out for the same reason `SwitcherPanel` is in the shell package: this
+ * codebase's bun:test environment has no DOM, so a state-driven variant can only be reached by
+ * rendering the hook-free piece directly, and the toggle's real `onClick` closure can only be
+ * invoked by calling this as a plain function. Not part of the package's barrel.
+ */
+export function InputBody(props) {
     const cls = ["input"];
     if (props.error)
         cls.push("is-err");
@@ -9,15 +41,89 @@ export function Input(props) {
         cls.push("is-dirty");
     if (props.readOnly)
         cls.push("readonly-input");
-    const field = (_jsxs(_Fragment, { children: [_jsx("input", { id: props.id, type: props.type ?? "text", class: cls.join(" "), value: props.value ?? "", placeholder: props.placeholder, disabled: props.disabled, readonly: props.readOnly, 
-                // Local single-user config UI: these are identifiers/paths/config values (slugs, names,
-                // model ids, urls), never autofill targets — kill browser autocomplete, the annoying
-                // first-letter auto-capitalize, autocorrect, and spellcheck squiggles on all of them.
-                autocomplete: "off", autocapitalize: "off", autocorrect: "off", spellcheck: false, "aria-invalid": props.error ? "true" : undefined, onInput: props.onInput ? (e) => props.onInput(e.target.value) : undefined, onKeyDown: props.onKeyDown }), props.help && !props.error ? _jsx("div", { class: "help", children: props.help }) : null, props.error ? (_jsxs("div", { class: "emsg", children: [_jsx("span", { "aria-hidden": "true", children: "\u26A0" }), _jsx("span", { children: props.error })] })) : null] }));
+    const type = props.type ?? "text";
+    const reveal = isRevealMode(props);
+    // The reveal path needs an id on the input: its toggle is a <button>, and a <button> is a
+    // labelable element — HTML forbids one inside a <label> that isn't labelling it, and the
+    // accessible-name computation would fold the button's own name ("Show token") into the
+    // input's. So that path swaps the wrapping-<label> form for an explicit for/id pairing.
+    // Every other path is untouched.
+    const id = props.id ?? (reveal ? props.autoId : undefined);
+    const control = (_jsx("input", { id: id, 
+        // The ONLY thing revealing changes: password ⇄ text on the field itself. The value is
+        // never copied anywhere else in the tree.
+        type: reveal && props.revealed ? "text" : type, class: cls.join(" "), value: props.value ?? "", placeholder: props.placeholder, disabled: props.disabled, readonly: props.readOnly, 
+        // Local single-user config UI: these are identifiers/paths/config values (slugs, names,
+        // model ids, urls), never autofill targets — kill browser autocomplete, the annoying
+        // first-letter auto-capitalize, autocorrect, and spellcheck squiggles on all of them.
+        // On the reveal path the field is a declared secret, and browsers/password managers largely
+        // IGNORE autocomplete="off" on type=password — they will autofill it and offer to save it
+        // as a login credential. `new-password` is what actually suppresses both, and is already
+        // this package's policy for credential entry (see MaskedSecretInput).
+        autocomplete: reveal ? "new-password" : "off", autocapitalize: "off", autocorrect: "off", spellcheck: false, "aria-invalid": props.error ? "true" : undefined, onInput: props.onInput ? (e) => props.onInput(e.target.value) : undefined, onKeyDown: props.onKeyDown }));
+    const field = (_jsxs(_Fragment, { children: [reveal ? (_jsxs("div", { class: "input-reveal", children: [control, _jsx(RevealToggle, { revealed: props.revealed, disabled: props.disabled, labels: props.revealLabels, onToggle: props.onToggleReveal })] })) : (control), props.help && !props.error ? _jsx("div", { class: "help", children: props.help }) : null, props.error ? (_jsxs("div", { class: "emsg", children: [_jsx("span", { "aria-hidden": "true", children: "\u26A0" }), _jsx("span", { children: props.error })] })) : null] }));
     if (!props.label)
         return field;
+    if (reveal) {
+        return (_jsxs("div", { class: "field", children: [_jsx("label", { class: "field-label", for: id, children: props.label }), field] }));
+    }
     return (_jsxs("label", { class: "field", children: [_jsx("span", { class: "field-label", children: props.label }), field] }));
 }
+/**
+ * Source of the reveal path's fallback field id.
+ *
+ * Deliberately NOT `useId`: that draws from preact's shared per-render id sequence, so taking one
+ * here would renumber the ids of every OTHER component in a consumer's tree — an invisible
+ * regression for an input that asked for none of this.
+ *
+ * A module counter is enough because this id never leaves the component. Its only job is to pair
+ * THIS instance's `<label for>` with THIS instance's `<input id>`, and both sides are the same
+ * value from the same render, so they cannot disagree with each other — which is the only
+ * property that has to hold.
+ *
+ * It follows that the counter's one give — a server render and its hydration draw from different
+ * counters, so the vdom's id and the hydrated DOM's id differ — is inert: preact does not rewrite
+ * attributes while hydrating, and any later patch moves both halves together. Reaching for
+ * `useId` to "fix" that would reintroduce a real, demonstrated regression (it renumbers every
+ * OTHER component's ids in the consumer's tree) in exchange for a mismatch nothing reads. Pass
+ * `id` yourself if you server-render and want a specific one.
+ */
+let revealIdSeq = 0;
+/** True when the field is a secret that opted into the reveal affordance. */
+export function isRevealMode(props) {
+    return props.revealable === true && (props.type ?? "text") === "password";
+}
+/**
+ * The reveal state to render this pass.
+ *
+ * ANY change of the field's mode clears it. A field that stops being a revealable secret and
+ * later becomes one again must come back hidden: the alternative is a password rendered in the
+ * clear that no one asked to see, on a render the user never touched.
+ */
+export function resolveRevealed(stored, storedMode, mode) {
+    return storedMode === mode ? stored : false;
+}
+export function Input(props) {
+    const mode = isRevealMode(props);
+    // `Input` always renders the same child component and always runs the same hooks, so flipping
+    // `revealable` or `type` re-renders the field instead of remounting it — a focused input keeps
+    // its focus, caret and selection. That makes clearing the reveal on a mode change this
+    // component's own job (see resolveRevealed), which is why the flag is a ref read during render
+    // rather than plain state: it has to be cleared on the very render that changes the mode.
+    //
+    // It is held here and never lifted into the props either way: a revealed secret must not
+    // survive a parent's re-render decision, and no consumer can force the field open.
+    const revealed = useRef(false);
+    const lastMode = useRef(mode);
+    const [, bumpRender] = useState(0);
+    revealed.current = resolveRevealed(revealed.current, lastMode.current, mode);
+    lastMode.current = mode;
+    const [autoId] = useState(() => `mythicalos-input-${++revealIdSeq}`);
+    return (_jsx(InputBody, { ...props, revealed: revealed.current, onToggleReveal: () => {
+            revealed.current = !revealed.current;
+            bumpRender((n) => n + 1);
+        }, autoId: autoId }));
+}
 export function Toggle(props) {
     const cls = ["tog"];
     if (!props.on)

package/dist/Popover.d.ts

@@ -0,0 +1,50 @@
+/** @jsxImportSource preact */
+import type { ComponentChildren, Ref } from "preact";
+import { type PopoverIds, type PopoverItem, type PopoverPosition } from "@mythicalos/ui-core/logic";
+export { POPOVER_CARET, POPOVER_CHECK, POPOVER_CLASS, POPOVER_EMPTY_VALUE, popoverItemClass, popoverPanelClass, popoverTriggerClass, popoverTriggerText, resolvePopoverPosition, type PopoverItem, type PopoverPosition, } from "@mythicalos/ui-core/logic";
+export interface PopoverProps {
+    /** The menu rows, in display order. Exactly one may carry `selected`. */
+    items: PopoverItem[];
+    /** Picking a row: closes the popover, returns focus to the trigger, then calls this. */
+    onSelect: (key: string, item: PopoverItem) => void;
+    /** Static prefix on the trigger, e.g. `"review lane:"`. */
+    label?: string;
+    /** Trigger value when nothing is selected (default: the em-dash placeholder). */
+    placeholder?: string;
+    /** Optional panel heading. */
+    title?: string;
+    /** Optional second heading line — the honest framing/caveat line. */
+    caption?: string;
+    /** Optional content below a divider (e.g. a "Manage projects →" action). Rows in here are the
+     * caller's own elements, and the arrow/Home/End roving deliberately does NOT reach them — a
+     * footer input keeps its own caret keys. Escape still closes from inside the footer. */
+    footer?: ComponentChildren;
+    disabled?: boolean;
+    /** Base for the trigger/panel id pair. Defaults to a generated one. */
+    id?: string;
+    /** Longer description for the trigger (native tooltip). Not the accessible NAME — the trigger's
+     * visible label + value already provide that. */
+    triggerTitle?: string;
+    onOpenChange?: (open: boolean) => void;
+}
+export interface PopoverPanelProps {
+    ids: PopoverIds;
+    pos: PopoverPosition;
+    items: PopoverItem[];
+    onPick: (item: PopoverItem) => void;
+    title?: string;
+    caption?: string;
+    footer?: ComponentChildren;
+    panelRef?: Ref<HTMLDivElement>;
+}
+/**
+ * The OPEN panel, deliberately hook-free (same testability split as the shell's `SwitcherPanel`):
+ * `preact-render-to-string` never runs effects or dispatches events, so the panel markup — and a
+ * row's REAL onClick closure, reachable off the returned vnode tree — would otherwise be
+ * unreachable from a DOM-free test. Exported from this module for tests; NOT part of the package
+ * barrel. `panelRef` rather than `ref` because plain Preact does not forward `ref` to a function
+ * component, and the React sibling keeps the same prop name so the two stay symmetric.
+ */
+export declare function PopoverPanel(props: PopoverPanelProps): import("preact").JSX.Element;
+/** A single-select dropdown popover anchored to its own chip trigger. */
+export declare function Popover(props: PopoverProps): import("preact").JSX.Element;