@mythicalos/preact-ui 0.2.1 → 0.3.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/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/hooks.js

@@ -64,10 +64,22 @@ export function usePoll(fn, ms, opts = {}) {
         let timer;
         let stopped = false;
         let failures = 0; // consecutive failed reads — drives the ×2 backoff ladder (reset on success)
+        // true from the moment a tick fires its fetch until that fetch settles — the ONE in-flight
+        // read this call site is allowed to have. The visibility handler below must never start a
+        // second tick while this is true; it lets the in-flight tick's own onSettled → schedule()
+        // continue the single chain instead (a prior version fired an immediate tick on visibility
+        // return unconditionally, which could open a second concurrent chain).
+        let pending = false;
         const isHidden = () => typeof document !== "undefined" && document.hidden === true;
         const schedule = () => {
             if (!alive || stopped)
                 return;
+            // Clear any already-armed timer before arming a new one — defense in depth so a stray
+            // double-settle can never leave an earlier timer orphaned (never cleared, still firing).
+            if (timer) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
             // U7 pause: while the document is hidden no timer is armed — the
             // visibilitychange handler below refreshes immediately on return.
             if (isHidden())
@@ -77,26 +89,31 @@ export function usePoll(fn, ms, opts = {}) {
         // diff r3-F1: every response routes through runPollTick — stamped with the epoch at fire
         // time, applied only while that epoch is still live. A stale settle leaves loading alone
         // (the reset already set it for the new epoch) but still rearms via schedule()'s own guards.
-        const tick = () => runPollTick({
-            fetch: () => fnRef.current(),
-            guard,
-            isAlive: () => alive && !stopped,
-            isHidden,
-            onSuccess: (v) => {
-                failures = 0;
-                setData(v);
-                setError(undefined);
-            },
-            onFailure: (message) => {
-                failures += 1;
-                setError(message);
-            },
-            onSettled: (applied) => {
-                if (applied)
-                    setLoading(false);
-                schedule();
-            },
-        });
+        const tick = () => {
+            pending = true;
+            return runPollTick({
+                fetch: () => fnRef.current(),
+                guard,
+                isAlive: () => alive && !stopped,
+                isHidden,
+                onSuccess: (v) => {
+                    failures = 0;
+                    setData(v);
+                    setError(undefined);
+                },
+                onFailure: (message) => {
+                    failures += 1;
+                    setError(message);
+                },
+                onSettled: (applied) => {
+                    if (applied)
+                        setLoading(false);
+                    schedule();
+                },
+            }).finally(() => {
+                pending = false;
+            });
+        };
         const onVisibility = () => {
             if (!alive || stopped)
                 return;
@@ -104,8 +121,10 @@ export function usePoll(fn, ms, opts = {}) {
                 clearTimeout(timer);
                 timer = undefined;
             }
-            if (!isHidden())
-                void tick(); // immediate refresh on visibility return
+            // Immediate refresh on visibility return — but only when idle. A tick already in flight
+            // keeps its place as the single chain: its own onSettled → schedule() picks up from here.
+            if (!isHidden() && !pending)
+                void tick();
         };
         if (typeof document !== "undefined")
             document.addEventListener("visibilitychange", onVisibility);

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { Button, buttonClass, type ButtonProps, type BtnVariant, type BtnState } from "./Button.js";
-export { Input, Toggle, Checkbox, type InputProps, type ToggleProps, type CheckboxProps } from "./Input.js";
+export { Input, Toggle, Checkbox, REVEAL_SHOW_LABEL, REVEAL_HIDE_LABEL, REVEAL_LABELS, type InputProps, type RevealLabels, type ToggleProps, type CheckboxProps, } from "./Input.js";
 export { MaskedSecretInput, type MaskedSecretInputProps } from "./MaskedSecretInput.js";
 export { EmptyState, type EmptyStateProps } from "./EmptyState.js";
 export { Scrim, ConfirmDialog, typedNameMatches, BULLET_ICON, type DialogBullet, type ConfirmDialogProps, } from "./ConfirmDialog.js";

package/dist/index.js

@@ -4,7 +4,7 @@
 // SearchInput, Banner, Gauge — Task 6). Serve `@mythicalos/ui-core/styles.css` (after
 // `@mythicalos/tokens`) so these components' classes resolve — this package ships no CSS of its own.
 export { Button, buttonClass } from "./Button.js";
-export { Input, Toggle, Checkbox } from "./Input.js";
+export { Input, Toggle, Checkbox, REVEAL_SHOW_LABEL, REVEAL_HIDE_LABEL, REVEAL_LABELS, } from "./Input.js";
 export { MaskedSecretInput } from "./MaskedSecretInput.js";
 export { EmptyState } from "./EmptyState.js";
 export { Scrim, ConfirmDialog, typedNameMatches, BULLET_ICON, } from "./ConfirmDialog.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mythicalos/preact-ui",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "mythicalOS thin Preact bindings over @mythicalos/ui-core — Button, Input/Toggle/Checkbox, MaskedSecretInput, EmptyState, ConfirmDialog/Scrim, Toast/ToastProvider, Chip, Card, Avatar, StatusLine, SearchInput, Banner, Gauge, and the usePoll/useInterval hooks. Render + framework wiring only — every class string, poll-scheduling math, glyph map, and text composition is derived by @mythicalos/ui-core so this binding and its React sibling can never drift. Apache-2.0.",
   "license": "Apache-2.0",
   "type": "module",
@@ -35,7 +35,7 @@
     }
   },
   "dependencies": {
-    "@mythicalos/ui-core": "^0.1.1"
+    "@mythicalos/ui-core": "^0.2.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",