@nanisoft/prism-ui 0.10.2 → 0.15.0

package/dist/components/ui/image-zoom.d.ts

@@ -0,0 +1,164 @@
+import { type ComponentProps, type ReactNode } from 'react';
+/** The props the ImageZoom accepts. */
+export interface ImageZoomProps extends Omit<ComponentProps<'div'>, 'children'> {
+    /** The image to magnify, at the resolution it should be magnified into. */
+    src: string;
+    /**
+     * The image's description, and required.
+     *
+     * Required for the reason it is required on `Lightbox`: an image with no
+     * description is a picture a reader can see more of and still not read, and
+     * this Component's whole purpose is that they see more of it. It is also the
+     * only thing that tells a screen reader what the thing they are magnifying is,
+     * because magnification changes no semantics at all: the element is still an
+     * `img` with this `alt` before, during and after.
+     */
+    alt: string;
+    /**
+     * The accessible name of the group, and required.
+     *
+     * A page with two magnified images is a page where a reader cannot tell which
+     * set of controls they are in, and the controls are three buttons that all
+     * look alike. The name is the caller's word, and `role="group"` is the
+     * deliberate choice over a landmark: a group is announced where it is met and
+     * never appears in a landmark list, so a page with six figures does not put six
+     * new entries in a reader's list of regions to walk.
+     */
+    label: string;
+    /**
+     * The words for the current magnification, and required.
+     *
+     * A function rather than a string, for the reason `Carousel`'s `position` is
+     * one: a magnification is a number and the sentence around it is different in
+     * every language, so the sentence is the caller's. It receives a percentage, not
+     * a multiplier, because a percentage is the form a reader reads and a
+     * multiplier is the form this Component stores.
+     */
+    scale: (percent: number) => string;
+    /**
+     * The smallest magnification, as a multiple of the fitted size. @defaultValue 1
+     *
+     * A number and not a keyword, because the useful answers are a designer's: the
+     * fitted size, twice the fitted size, and a figure from the caller's own brief.
+     */
+    minScale?: number;
+    /** The largest. @defaultValue 4 */
+    maxScale?: number;
+    /** How much one press moves it. @defaultValue 0.5 */
+    step?: number;
+    /**
+     * The accessible name of the control that magnifies, and required.
+     *
+     * Required rather than defaulted on the reasoning `Lightbox` states: a
+     * hardcoded accessible name is a sentence a consumer cannot localise, and the
+     * only fix is a fork of this package. The three names are the caller's because
+     * they are three sentences in the caller's own words, and because "Zoom" is
+     * not the word a German product says for it.
+     */
+    zoomInLabel: string;
+    /** The accessible name of the control that reduces the magnification. */
+    zoomOutLabel: string;
+    /** The accessible name of the control that returns the image to its fitted size. */
+    resetLabel: string;
+    /**
+     * The caller's own controls, drawn after this Component's three.
+     *
+     * A slot and not a second set of props, because everything a reader might want
+     * beside a magnifier is the consumer's decision: a download, a "show the whole
+     * page" that hands off to `Lightbox`, a reset for the surrounding form. Prism
+     * draws the three controls it can get right, and this is where the rest go. The
+     * cost is that a caller who wants their own magnification controls cannot
+     * suppress these three, and the answer is that a magnifier whose only route to
+     * magnification is in someone else's markup is not a magnifier.
+     */
+    controls?: ReactNode;
+    /**
+     * Called with the magnification after every press.
+     *
+     * A notification rather than a controlled prop, and the reason is the same as
+     * `Lightbox`'s reset: the magnification is a decision about this visit. A
+     * reader who magnified a diagram, went away and came back should find it as
+     * they left it, not as they found it, so it is held here and not lifted. What
+     * the caller usually wants the number for is layout, and a notification is
+     * enough for that.
+     */
+    onScaleChange?: (scale: number) => void;
+    /** Layout only, exactly as on every Component. */
+    className?: string;
+}
+/**
+ * An image the reader magnifies where it already sits, with a frame that scrolls
+ * once it is larger than its box.
+ *
+ * **It is the `Lightbox` with the dialog taken out, and that subtraction is the
+ * whole Component.** A `Lightbox` opens a portal, traps focus, locks page scroll,
+ * swallows the Escape key and hands the reader a different place in the document
+ * to come back from. All five of those are the right price for an image the page
+ * has not shown the reader at all, where the enlargement is the only way to see
+ * it. They are the wrong price for an image the reader is already looking at:
+ * paying a focus trap to make a picture on the page bigger costs the reader their
+ * scroll position, their place in the document and their focus context, and a
+ * reader who has magnified an inline diagram and then closed the dialog lands
+ * somewhere they have to find again. So there is no portal, no overlay, no trap,
+ * no Escape key and no dismiss here. The page does not move and nothing is taken
+ * away from it. **Use a `Lightbox` when the enlargement is the only route to the
+ * image; use this when the image is already on the page and only its size is in
+ * the way.**
+ *
+ * **Prism draws the three controls and asks for their names, rather than taking
+ * the controls as a slot.** A slot would move the one guarantee that makes a
+ * magnifier usable to the caller: that the controls exist, that they are real
+ * buttons in the tab order, that they are disabled at the ends of the range, and
+ * that a reader whose control has just been disabled is moved to one that still
+ * works. That last one is not obvious and `Carousel` had to write a `useEffect`
+ * to get it right, because a disabled button leaves the tab order without giving
+ * up focus: a reader who presses zoom in at the ceiling is left focused on a
+ * control that can no longer answer Enter, Space or anything else, stranded
+ * inside the magnifier with no working control under their fingers. This
+ * Component does that move itself. The cost is that a caller who wants their own
+ * magnification controls cannot have them here, and the answer is that this is
+ * the wrong Component for a caller who wants that.
+ *
+ * **The scale transition is a transform with a token duration, and it is the only
+ * motion on the surface.** Magnifying a picture is spatial movement of a whole
+ * surface, so a reader who has asked for reduced motion gets the new size
+ * immediately and loses nothing but the travel between the two. Nothing here is
+ * guarded per call site any more: `packages/ui/src/styles.css` stops every
+ * transition under `prefers-reduced-motion` in one unlayered rule, and a
+ * `motion-safe:` beside an unguarded `transition-transform` was inert rather than
+ * cautious. The transition is on `transform` and on nothing else: an animated
+ * `width` or `height` is a layout animation on the main thread, which is the
+ * defect the compositor rule in the ambient layer exists to prevent, and a
+ * magnified diagram is large enough for that to be visible.
+ *
+ * **The scale reaches its final value before the pixels do, and that is the
+ * price of using a transform.** A transform does not change layout, so the
+ * frame's scroll extent is already at its full size on the first frame of the
+ * transition and the scrollbar arrives while the image is still travelling. The
+ * alternative is to animate the image's own size, which is a main-thread layout
+ * animation on the largest element on the page, and a scrollbar that moves a
+ * fraction early is a cheaper defect than a stuttering diagram.
+ *
+* **Panning is a scroll, not a gesture.** Once the image is larger than its frame
+ * the frame scrolls, and the reader pans with the keys they already use: the
+ * arrow keys, the space bar, the Home and End keys, and a trackpad or a finger.
+ * There is no drag to pan, no pinch and no double tap, for the reason
+ * `Lightbox` gives: each of those is a bespoke pointer model a reader has to
+ * discover, and a scrollable frame is a thing every reader already knows. The
+ * frame is a block rather than a centred flex row, because a centred child
+ * larger than its scroll container has a left edge that cannot be scrolled back
+ * to in more than one browser, and a magnified image is routinely larger than
+ * its frame.
+ *
+ * **The scale is announced, politely, in the caller's words.** The sentence is in
+   * an `aria-live="polite"` region beside the controls, so a reader who has just
+   * pressed a button is told where they are without the announcement interrupting
+   * whatever they were reading. It is polite rather than assertive for the same
+   * reason `Carousel`'s position is: the reader caused the change by pressing a
+   * control and does not need to be interrupted by it.
+ *
+ * It is a client Component, because it holds a magnification and answers presses.
+ */
+declare function ImageZoom({ src, alt, label, scale, minScale, maxScale, step, zoomInLabel, zoomOutLabel, resetLabel, controls, onScaleChange, className, ...props }: ImageZoomProps): import("react").JSX.Element;
+export { ImageZoom };
+//# sourceMappingURL=image-zoom.d.ts.map

package/dist/components/ui/image-zoom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-zoom.d.ts","sourceRoot":"","sources":["../../../src/components/ui/image-zoom.tsx"],"names":[],"mappings":"AAGA,OAAO,EAA4C,KAAK,cAAc,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAgBrG,uCAAuC;AACvC,MAAM,WAAW,cAAe,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAC7E,2EAA2E;IAC3E,GAAG,EAAE,MAAM,CAAA;IACX;;;;;;;;;OASG;IACH,GAAG,EAAE,MAAM,CAAA;IACX;;;;;;;;;OASG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;OAQG;IACH,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAA;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;;;OAQG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB,yEAAyE;IACzE,YAAY,EAAE,MAAM,CAAA;IACpB,oFAAoF;IACpF,UAAU,EAAE,MAAM,CAAA;IAClB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AA6BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AACH,iBAAS,SAAS,CAAC,EACjB,GAAG,EACH,GAAG,EACH,KAAK,EACL,KAAK,EACL,QAAc,EACd,QAAkB,EAClB,IAAa,EACb,WAAW,EACX,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,aAAa,EACb,SAAS,EACT,GAAG,KAAK,EACT,EAAE,cAAc,+BAyJhB;AAED,OAAO,EAAE,SAAS,EAAE,CAAA"}

package/dist/components/ui/image-zoom.js

@@ -0,0 +1,169 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ScanIcon, ZoomInIcon, ZoomOutIcon } from 'lucide-react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { cn } from '../../lib/utils.js';
+/**
+ * The magnification the Component holds at its smallest, and the value it returns
+ * to, as a multiple of the image's fitted size.
+ */
+const FIT = 1;
+/** The largest magnification offered when the caller names none. */
+const CEILING = 4;
+/** How much one press moves the magnification when the caller names no step. */
+const STRIDE = 0.5;
+/**
+ * The magnification every control in this Component draws.
+ *
+ * One string rather than three, for the reason `drawer.tsx` states: a control bar
+ * where the out control has its own metrics and the reset has another is a bar a
+ * reader moving by Tab finds unevenly spaced, and the difference is invisible in
+ * review.
+ *
+ * `pointer-coarse:size-11` is the coarse-pointer floor, as a step, because the bar
+ * is `flex flex-wrap items-center gap-2` and a bordered box at 44px is what a finger
+ * aims at. A band was rejected on condition 1: the controls sit eight pixels apart,
+ * and a 44px band centred on a 36px box overhangs its box by four on each side, which
+ * lands inside that gap rather than on a neighbour, so the band would buy eight
+ * pixels of reach for a target that is already only eight short and would leave the
+ * drawn box at 36. See DESIGN.md, The coarse-pointer floor.
+ */
+const CONTROL = 'text-muted-foreground hover:text-foreground border-input bg-background inline-flex size-9 items-center justify-center rounded-md border outline-none transition-colors duration-fast ease-out disabled:pointer-events-none disabled:opacity-50 focus-visible:ring-ring focus-visible:ring-[3px]' +
+    ' pointer-coarse:size-11';
+/** A magnification inside the caller's bounds, so no press can leave the range. */
+function bound(value, low, high) {
+    if (!Number.isFinite(value))
+        return low;
+    if (high < low)
+        return low;
+    return Math.min(Math.max(value, low), high);
+}
+/**
+ * An image the reader magnifies where it already sits, with a frame that scrolls
+ * once it is larger than its box.
+ *
+ * **It is the `Lightbox` with the dialog taken out, and that subtraction is the
+ * whole Component.** A `Lightbox` opens a portal, traps focus, locks page scroll,
+ * swallows the Escape key and hands the reader a different place in the document
+ * to come back from. All five of those are the right price for an image the page
+ * has not shown the reader at all, where the enlargement is the only way to see
+ * it. They are the wrong price for an image the reader is already looking at:
+ * paying a focus trap to make a picture on the page bigger costs the reader their
+ * scroll position, their place in the document and their focus context, and a
+ * reader who has magnified an inline diagram and then closed the dialog lands
+ * somewhere they have to find again. So there is no portal, no overlay, no trap,
+ * no Escape key and no dismiss here. The page does not move and nothing is taken
+ * away from it. **Use a `Lightbox` when the enlargement is the only route to the
+ * image; use this when the image is already on the page and only its size is in
+ * the way.**
+ *
+ * **Prism draws the three controls and asks for their names, rather than taking
+ * the controls as a slot.** A slot would move the one guarantee that makes a
+ * magnifier usable to the caller: that the controls exist, that they are real
+ * buttons in the tab order, that they are disabled at the ends of the range, and
+ * that a reader whose control has just been disabled is moved to one that still
+ * works. That last one is not obvious and `Carousel` had to write a `useEffect`
+ * to get it right, because a disabled button leaves the tab order without giving
+ * up focus: a reader who presses zoom in at the ceiling is left focused on a
+ * control that can no longer answer Enter, Space or anything else, stranded
+ * inside the magnifier with no working control under their fingers. This
+ * Component does that move itself. The cost is that a caller who wants their own
+ * magnification controls cannot have them here, and the answer is that this is
+ * the wrong Component for a caller who wants that.
+ *
+ * **The scale transition is a transform with a token duration, and it is the only
+ * motion on the surface.** Magnifying a picture is spatial movement of a whole
+ * surface, so a reader who has asked for reduced motion gets the new size
+ * immediately and loses nothing but the travel between the two. Nothing here is
+ * guarded per call site any more: `packages/ui/src/styles.css` stops every
+ * transition under `prefers-reduced-motion` in one unlayered rule, and a
+ * `motion-safe:` beside an unguarded `transition-transform` was inert rather than
+ * cautious. The transition is on `transform` and on nothing else: an animated
+ * `width` or `height` is a layout animation on the main thread, which is the
+ * defect the compositor rule in the ambient layer exists to prevent, and a
+ * magnified diagram is large enough for that to be visible.
+ *
+ * **The scale reaches its final value before the pixels do, and that is the
+ * price of using a transform.** A transform does not change layout, so the
+ * frame's scroll extent is already at its full size on the first frame of the
+ * transition and the scrollbar arrives while the image is still travelling. The
+ * alternative is to animate the image's own size, which is a main-thread layout
+ * animation on the largest element on the page, and a scrollbar that moves a
+ * fraction early is a cheaper defect than a stuttering diagram.
+ *
+* **Panning is a scroll, not a gesture.** Once the image is larger than its frame
+ * the frame scrolls, and the reader pans with the keys they already use: the
+ * arrow keys, the space bar, the Home and End keys, and a trackpad or a finger.
+ * There is no drag to pan, no pinch and no double tap, for the reason
+ * `Lightbox` gives: each of those is a bespoke pointer model a reader has to
+ * discover, and a scrollable frame is a thing every reader already knows. The
+ * frame is a block rather than a centred flex row, because a centred child
+ * larger than its scroll container has a left edge that cannot be scrolled back
+ * to in more than one browser, and a magnified image is routinely larger than
+ * its frame.
+ *
+ * **The scale is announced, politely, in the caller's words.** The sentence is in
+   * an `aria-live="polite"` region beside the controls, so a reader who has just
+   * pressed a button is told where they are without the announcement interrupting
+   * whatever they were reading. It is polite rather than assertive for the same
+   * reason `Carousel`'s position is: the reader caused the change by pressing a
+   * control and does not need to be interrupted by it.
+ *
+ * It is a client Component, because it holds a magnification and answers presses.
+ */
+function ImageZoom({ src, alt, label, scale, minScale = FIT, maxScale = CEILING, step = STRIDE, zoomInLabel, zoomOutLabel, resetLabel, controls, onScaleChange, className, ...props }) {
+    const [at, setAt] = useState(FIT);
+    /*
+     * The caller's range, made into a range that can hold. A magnification that is
+     * not a positive number is a division that has not happened yet, and a ceiling
+     * that is not above the floor is two numbers that cannot both be true. In
+     * either case the fitted size and the default ceiling are drawn instead rather
+     * than a range that magnifies the wrong way or refuses to move, and the value
+     * actually in force is reported on the frame as `data-scale`, so a substituted
+     * bound is legible in the markup rather than only in the screenshot. That is
+     * `AspectRatio`'s rule about a value that cannot be drawn, applied to a range.
+     */
+    const low = Number.isFinite(minScale) && minScale > 0 ? minScale : FIT;
+    const high = Number.isFinite(maxScale) && maxScale > low ? maxScale : Math.max(CEILING, low);
+    const stride = Number.isFinite(step) && step !== 0 ? Math.abs(step) : STRIDE;
+    const zoomIn = useRef(null);
+    const zoomOut = useRef(null);
+    const set = useCallback((next) => {
+        const value = bound(next, low, high);
+        setAt(value);
+        onScaleChange?.(value);
+    }, [high, low, onScaleChange]);
+    const magnified = at > FIT;
+    const atFloor = at <= low;
+    const atCeiling = at >= high;
+    /*
+     * A control that has just been disabled must not keep the reader's focus. A
+     * disabled button is out of the tab order and does not give up focus, so a
+     * reader who magnifies to the ceiling is left focused on a control that can no
+     * longer answer anything. Focus is handed to the sibling that is still live,
+     * which is what a browser does when focus lands on something that has become
+     * inert, and only when the stranded control is one of this Component's two.
+     */
+    useEffect(() => {
+        const active = document.activeElement;
+        if (!(active instanceof HTMLButtonElement))
+            return;
+        if (active !== zoomIn.current && active !== zoomOut.current)
+            return;
+        if (active.disabled !== true)
+            return;
+        const live = active === zoomIn.current ? zoomOut.current : zoomIn.current;
+        if (live === null || live.disabled)
+            return;
+        live.focus();
+    });
+    return (_jsxs("div", { "data-slot": "image-zoom", role: "group", "aria-label": label, className: cn('flex flex-col gap-2', className), ...props, children: [_jsx("div", { "data-slot": "image-zoom-frame", "data-scale": at, "data-zoomed": magnified || undefined, className: "overflow-auto overscroll-contain", children: _jsx("img", { "data-slot": "image-zoom-image", src: src, alt: alt, 
+                    // A transform is the one value on this element that is not a utility
+                    // class, and the reason is that the magnification is a number the
+                    // caller passed rather than one of a closed set Prism authored. A
+                    // utility would be a closed list of factors, and a magnifier whose
+                    // ceiling is whichever factor the caller happened to be closest to is a
+                    // magnifier that rounds the reader's request.
+                    style: { transform: `scale(${at})` }, className: "block h-auto w-full origin-top-left transition-transform duration-base ease-out" }) }), _jsxs("div", { "data-slot": "image-zoom-controls", className: "flex flex-wrap items-center gap-2", children: [_jsx("button", { type: "button", ref: zoomOut, "data-slot": "image-zoom-out", "aria-label": zoomOutLabel, disabled: atFloor, onClick: () => set(at - stride), className: CONTROL, children: _jsx(ZoomOutIcon, { className: "size-4", "aria-hidden": "true" }) }), magnified ? (_jsx("button", { type: "button", "data-slot": "image-zoom-reset", "aria-label": resetLabel, onClick: () => set(low), className: CONTROL, children: _jsx(ScanIcon, { className: "size-4", "aria-hidden": "true" }) })) : null, _jsx("button", { type: "button", ref: zoomIn, "data-slot": "image-zoom-in", "aria-label": zoomInLabel, disabled: atCeiling, onClick: () => set(at + stride), className: CONTROL, children: _jsx(ZoomInIcon, { className: "size-4", "aria-hidden": "true" }) }), _jsx("p", { "data-slot": "image-zoom-scale", "aria-live": "polite", className: "text-muted-foreground text-sm tabular-nums", children: scale(Math.round(at * 100)) }), controls] })] }));
+}
+export { ImageZoom };

package/dist/components/ui/input-group.d.ts

@@ -0,0 +1,99 @@
+import type { ComponentProps } from 'react';
+import { Input } from './input.js';
+/**
+ * Where an addon sits in the group, and what its border does about it.
+ *
+ * The addon keeps its own border on the outer edge only, because the group
+ * already draws the edge it shares with the control. Two borders on the same line
+ * read as a seam down the middle of one field, which is the opposite of what
+ * joining them was for.
+ */
+declare const ADDON_POSITION: {
+    readonly prefix: "rounded-s-md border-e-0";
+    readonly suffix: "rounded-e-md border-s-0";
+};
+/** The props the Input group accepts. */
+export interface InputGroupProps extends ComponentProps<'div'> {
+    /**
+     * Whether the group ignores interaction.
+     *
+     * Drawn rather than set: the group's own `disabled` attribute would disable the
+     * control in the middle of it without the reader's pointer ever touching it, and
+     * a `<div>` cannot be disabled. Put `disabled` on the control and the group dims
+     * itself.
+     */
+    disabled?: boolean;
+}
+/** The props the Input group addon accepts. */
+export interface InputGroupAddonProps extends ComponentProps<'div'> {
+    /** Which end of the group the addon sits on. @defaultValue prefix */
+    position?: keyof typeof ADDON_POSITION;
+}
+/** The props the Input group input accepts. */
+export type InputGroupInputProps = ComponentProps<typeof Input>;
+/** The props the Input group button accepts. */
+export interface InputGroupButtonProps extends ComponentProps<'button'> {
+    /** Which end of the group the button sits on. @defaultValue suffix */
+    position?: keyof typeof ADDON_POSITION;
+}
+/**
+ * Related controls drawn as one field: a prefix, a suffix, a unit, an action.
+ *
+ * **The addons are part of the field, not beside it.** They share one border, one
+ * height, one corner radius and one focus colour, because the thing they decorate
+ * is the field and a reader who sees three boxes has been given three things to
+ * reason about where they were given one. A currency symbol and the number it
+ * belongs to are one field with two parts, and the Component draws them as one
+ * field.
+ *
+ * **The frame answers the focus, the control draws the ring.** The group is a
+ * `div`: it is never focused and it has nothing to ring. It turns its border to the
+ * ring token when anything inside it has focus, and the control, which is the
+ * element that actually has focus, keeps `Input`'s own full-strength ring. Two
+ * indicators would be two things to read, and putting the ring on a wrapper that
+ * is not the thing being operated is how a focus indicator ends up drawn around
+ * the wrong box.
+ *
+ * **Use `InputGroupInput` inside it rather than `Input`.** A bordered `Input`
+ * inside a bordered group draws a second border inside the first, and the caller
+ * should not have to know that `border-0 shadow-none` is the fix. The rest of the
+ * surface is plain divs and buttons, so a caller can put any control in the middle
+ * once they know they have to take its border off.
+ *
+ * It is presentational: it renders no state of its own, has no hooks and no event
+ * handlers, so it is a server Component and a consumer's field costs no client
+ * JavaScript for the frame. Pair it with a `Label` above it and the control inside
+ * is the only thing that needs a name.
+ */
+declare function InputGroup({ className, disabled, ...props }: InputGroupProps): import("react").JSX.Element;
+/**
+ * A static run of words or an icon inside the group: a unit, a prefix, a currency
+ * symbol, a field name.
+ *
+ * It carries no accessible name of its own and none is needed: the text inside it
+ * is read in place, and the control it belongs to is named by the label above the
+ * group. Use `InputGroupButton` when the part has to be operated, so it gets a
+ * name and a focus ring of its own.
+ */
+declare function InputGroupAddon({ className, position, ...props }: InputGroupAddonProps): import("react").JSX.Element;
+/**
+ * The control in the middle of the group, without a border of its own.
+ *
+ * A thin composition over `Input` rather than a variant of it, so the field keeps
+ * every behaviour a plain `Input` has, including its focus ring, its `aria-invalid`
+ * border and its disabled state. Only the border and the shadow are dropped,
+ * because the group already draws both.
+ */
+declare function InputGroupInput({ className, ...props }: InputGroupInputProps): import("react").JSX.Element;
+/**
+ * An operable part inside the group: clear the field, reveal a password, open a
+ * picker.
+ *
+ * A button rather than an addon, because the moment the part can be operated it
+ * needs its own accessible name, its own focus ring and its own press feedback,
+ * and an addon has none of the three. The name is a prop, as it is everywhere:
+ * "Clear" is a word this package does not get to choose for a consumer's product.
+ */
+declare function InputGroupButton({ className, position, type, ...props }: InputGroupButtonProps): import("react").JSX.Element;
+export { InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput };
+//# sourceMappingURL=input-group.d.ts.map

package/dist/components/ui/input-group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-group.d.ts","sourceRoot":"","sources":["../../../src/components/ui/input-group.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAE3C,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAG/B;;;;;;;GAOG;AACH,QAAA,MAAM,cAAc;;;CAGV,CAAA;AAEV,yCAAyC;AACzC,MAAM,WAAW,eAAgB,SAAQ,cAAc,CAAC,KAAK,CAAC;IAC5D;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,+CAA+C;AAC/C,MAAM,WAAW,oBAAqB,SAAQ,cAAc,CAAC,KAAK,CAAC;IACjE,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,OAAO,cAAc,CAAA;CACvC;AAED,+CAA+C;AAC/C,MAAM,MAAM,oBAAoB,GAAG,cAAc,CAAC,OAAO,KAAK,CAAC,CAAA;AAE/D,gDAAgD;AAChD,MAAM,WAAW,qBAAsB,SAAQ,cAAc,CAAC,QAAQ,CAAC;IACrE,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,OAAO,cAAc,CAAA;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,iBAAS,UAAU,CAAC,EAAE,SAAS,EAAE,QAAgB,EAAE,GAAG,KAAK,EAAE,EAAE,eAAe,+BAgB7E;AAED;;;;;;;;GAQG;AACH,iBAAS,eAAe,CAAC,EAAE,SAAS,EAAE,QAAmB,EAAE,GAAG,KAAK,EAAE,EAAE,oBAAoB,+BAa1F;AAED;;;;;;;GAOG;AACH,iBAAS,eAAe,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,oBAAoB,+BAQrE;AAED;;;;;;;;GAQG;AACH,iBAAS,gBAAgB,CAAC,EACxB,SAAS,EACT,QAAmB,EACnB,IAAe,EACf,GAAG,KAAK,EACT,EAAE,qBAAqB,+BAiBvB;AAED,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,gBAAgB,EAAE,eAAe,EAAE,CAAA"}

package/dist/components/ui/input-group.js

@@ -0,0 +1,83 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Input } from './input.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * Where an addon sits in the group, and what its border does about it.
+ *
+ * The addon keeps its own border on the outer edge only, because the group
+ * already draws the edge it shares with the control. Two borders on the same line
+ * read as a seam down the middle of one field, which is the opposite of what
+ * joining them was for.
+ */
+const ADDON_POSITION = {
+    prefix: 'rounded-s-md border-e-0',
+    suffix: 'rounded-e-md border-s-0',
+};
+/**
+ * Related controls drawn as one field: a prefix, a suffix, a unit, an action.
+ *
+ * **The addons are part of the field, not beside it.** They share one border, one
+ * height, one corner radius and one focus colour, because the thing they decorate
+ * is the field and a reader who sees three boxes has been given three things to
+ * reason about where they were given one. A currency symbol and the number it
+ * belongs to are one field with two parts, and the Component draws them as one
+ * field.
+ *
+ * **The frame answers the focus, the control draws the ring.** The group is a
+ * `div`: it is never focused and it has nothing to ring. It turns its border to the
+ * ring token when anything inside it has focus, and the control, which is the
+ * element that actually has focus, keeps `Input`'s own full-strength ring. Two
+ * indicators would be two things to read, and putting the ring on a wrapper that
+ * is not the thing being operated is how a focus indicator ends up drawn around
+ * the wrong box.
+ *
+ * **Use `InputGroupInput` inside it rather than `Input`.** A bordered `Input`
+ * inside a bordered group draws a second border inside the first, and the caller
+ * should not have to know that `border-0 shadow-none` is the fix. The rest of the
+ * surface is plain divs and buttons, so a caller can put any control in the middle
+ * once they know they have to take its border off.
+ *
+ * It is presentational: it renders no state of its own, has no hooks and no event
+ * handlers, so it is a server Component and a consumer's field costs no client
+ * JavaScript for the frame. Pair it with a `Label` above it and the control inside
+ * is the only thing that needs a name.
+ */
+function InputGroup({ className, disabled = false, ...props }) {
+    return (_jsx("div", { "data-slot": "input-group", "data-disabled": disabled || undefined, "aria-disabled": disabled || undefined, className: cn('border-input bg-background focus-within:border-ring flex w-full items-stretch rounded-md border shadow-xs', 'transition-[color,box-shadow] duration-fast ease-out', 'has-[input:disabled]:opacity-50', disabled && 'opacity-50', className), ...props }));
+}
+/**
+ * A static run of words or an icon inside the group: a unit, a prefix, a currency
+ * symbol, a field name.
+ *
+ * It carries no accessible name of its own and none is needed: the text inside it
+ * is read in place, and the control it belongs to is named by the label above the
+ * group. Use `InputGroupButton` when the part has to be operated, so it gets a
+ * name and a focus ring of its own.
+ */
+function InputGroupAddon({ className, position = 'prefix', ...props }) {
+    return (_jsx("div", { "data-slot": "input-group-addon", "data-position": position, className: cn('bg-muted text-muted-foreground border-input flex shrink-0 items-center border px-2.5 text-sm', ADDON_POSITION[position], className), ...props }));
+}
+/**
+ * The control in the middle of the group, without a border of its own.
+ *
+ * A thin composition over `Input` rather than a variant of it, so the field keeps
+ * every behaviour a plain `Input` has, including its focus ring, its `aria-invalid`
+ * border and its disabled state. Only the border and the shadow are dropped,
+ * because the group already draws both.
+ */
+function InputGroupInput({ className, ...props }) {
+    return (_jsx(Input, { "data-slot": "input-group-input", className: cn('flex-1 border-0 shadow-none focus-visible:border-0', className), ...props }));
+}
+/**
+ * An operable part inside the group: clear the field, reveal a password, open a
+ * picker.
+ *
+ * A button rather than an addon, because the moment the part can be operated it
+ * needs its own accessible name, its own focus ring and its own press feedback,
+ * and an addon has none of the three. The name is a prop, as it is everywhere:
+ * "Clear" is a word this package does not get to choose for a consumer's product.
+ */
+function InputGroupButton({ className, position = 'suffix', type = 'button', ...props }) {
+    return (_jsx("button", { type: type, "data-slot": "input-group-button", "data-position": position, className: cn('border-input text-muted-foreground hover:bg-accent hover:text-accent-foreground flex shrink-0 items-center justify-center border px-2.5 text-sm outline-none', 'transition-[color,background-color] duration-fast ease-out', 'focus-visible:ring-ring focus-visible:ring-[3px]', 'disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50', ADDON_POSITION[position], className), ...props }));
+}
+export { InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput };

package/dist/components/ui/input.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { cn } from '../../lib/utils';
+import { cn } from '../../lib/utils.js';
 /**
  * The single-line text control.
  *