@nanisoft/prism-ui 0.13.0 → 0.15.0

package/dist/components/ui/pill.d.ts

@@ -0,0 +1,172 @@
+import type { ComponentProps, ReactNode } from 'react';
+/**
+ * The five fills a pill is drawn in, and the same five a tag is drawn in.
+ *
+ * The five are the semantic contract's, and each is a fill with a matched ink, so
+ * a pill in a scoped pack boundary re-inks with everything around it. `info` is
+ * the brand hue at a tenth's strength with a border at four tenths, because the
+ * contract publishes no information role and inventing one here would be a second
+ * place a new colour gets decided.
+ *
+ * **The table is written out rather than imported from `tag-group`, and the cost
+ * of that is a change in one place being a change in the other.** A shared module
+ * would be a third Item with no job of its own, or a file under the package's
+ * internal `lib`, where a new declaration has to be declared in the surface gate
+ * before it can ship, so the only two shapes that reach a consumer without a
+ * change somewhere else are a duplicate table and a new surface. The duplicate is
+ * the cheaper of the two, and the drift it risks is bounded: five lines, all of
+ * which name contract roles rather than a chosen colour, and every one of which
+ * the contrast gate already measures.
+ *
+ * `neutral` is the answer when there is nothing to say, and it is the default for
+ * that reason rather than because it is the least interesting.
+ */
+export type PillTone = 'neutral' | 'info' | 'success' | 'warning' | 'destructive';
+/**
+ * The two steps a pill is drawn at, as frame and label together.
+ *
+ * The pair moves as one because a pill whose label is set at one step and padded
+ * at the other is a chip with a hole in the middle of it: the extra leading
+ * reads as a mistake in the fill rather than as room for the label. `sm` is for a
+ * dense table row, a filter summary and a chart legend, and `md` is for a row a
+ * reader is meant to read. There is no third step because a chip set larger than
+ * `md` is a `Badge` at a different size and a `Badge` is the Component for a
+ * status the system decided.
+ */
+declare const PILL_SIZE: {
+    readonly sm: {
+        readonly frame: "gap-1 px-2 py-0.5 text-xs";
+        readonly label: "font-medium";
+    };
+    readonly md: {
+        readonly frame: "gap-1.5 px-2.5 py-1 text-sm";
+        readonly label: "font-medium";
+    };
+};
+/** The props a `Pill` accepts. */
+export type PillProps = Omit<ComponentProps<'span'>, 'children'> & {
+    /**
+     * What the chip says, in the words a reader would use about it.
+     *
+     * Required, and a node rather than a string because a pill is often a mark and
+     * a word, or a word and a count, and a `string` prop would make a caller wrap
+     * their own mark in a string to smuggle it through. A node also means the
+     * element a sighted reader reads is the element a screen reader names the pill
+     * by, with no second copy of the sentence to keep in step.
+     */
+    label: ReactNode;
+    /**
+     * The fill the pill is drawn in. @defaultValue 'neutral'
+     *
+     * The tone is the caller's because it is a claim about the value rather than
+     * about the design system. A tier, a recipient, a filter, a licence key and a
+     * network segment are all pills, and which of them deserves the destructive fill
+     * is the caller's judgement about their own product.
+     */
+    tone?: PillTone;
+    /**
+     * The drawn step of the pill. @defaultValue 'md'
+     *
+     * See `PILL_SIZE` for why there are two and not three.
+     */
+    size?: keyof typeof PILL_SIZE;
+    /**
+     * A node before the label, for a mark that is not the label: an avatar, a
+     * monogram, a severity dot, a `Status`.
+     *
+     * A slot rather than an `icon` prop, for the reason the whole package uses
+     * slots for marks. Prism's icon lane is Lucide and its mark lane is the
+     * caller's own assets, and an `icon` prop would force one of the two on every
+     * caller while refusing the other. The slot is also the reason a caller can put
+     * something interactive at the leading edge, which a fixed `size-4` glyph could
+     * never hold.
+     */
+    leading?: ReactNode;
+    /**
+     * A node after the label, for whatever comes last: a count, a unit, a state, or
+     * a control the caller owns.
+     *
+     * **The remove affordance is here and not drawn by this Component, and that is
+     * the decision this Item exists to be different about.** `Tag` draws an X and
+     * requires a name for it, because a tag is by definition a value in a set the
+     * reader can take back and one affordance is the whole of that. A pill is one
+     * value on its own, and a value on its own has at least as many reasons to end
+     * in something that is not a cross: a count of what the pill counts, a state
+     * the value is in, a link to the record it names. So the slot is a slot, the
+     * caller puts their own `Button` in it, and that control carries its own
+     * accessible name, its own confirmation and its own coarse-pointer target. The
+     * cost is stated rather than hidden: Prism cannot check that the control in the
+     * slot has a name, which is the one thing `Tag` enforces by throwing, so a
+     * caller who puts an unlabelled button there ships an unlabelled button.
+     */
+    trailing?: ReactNode;
+    /** Layout only, exactly as on every Component. */
+    className?: string;
+};
+/**
+ * One small fully rounded chip, holding one value, with a slot at each end.
+ *
+ * **It is not a `Tag`, and the two differences are both load bearing rather than
+ * cosmetic.** The first is the shape. A pill is fully rounded, and full rounding
+ * is the one radius a pack boundary is allowed to sit on, because
+ * `--radius-sm` through `--radius-4xl` are all computed from the pack's own
+ * `--radius` by multiplication: a `rounded-md` chip carrying a `data-pack`
+ * boundary is a chip whose corners move with its colour, and a row of six of them
+ * shows five different corner radii for one pack. `Tag` is a `rounded-md` chip
+ * because it is a chip in a running row, where a capsule per chip reads as a row
+ * of buttons, and a pill is a capsule because it is one value standing on its own
+ * and because the shape is the reason a `PackSwatch` and a pill can sit in the
+ * same row without one of them moving. The second is the two slots, which is
+ * where the cross of a `Tag` lives, and the argument for both is on `trailing`.
+ *
+ * **It is a single pill and not a group, and there is no `PillGroup` to be
+ * asked for later.** A set of values is `TagGroup`, which wraps, which labels
+ * itself, which owns the remove handler and which is a client Component the
+ * moment that handler is passed. A pill holds one value and the arrangement
+ * around it is the caller's, so a table cell, a chart legend, a summary line and
+ * a card header each get a pill and none of them gets a role or a heading nobody
+ * asked for. The cost is that a caller with six pills writes the row, and writes
+ * the gap and the wrap and the accessible name for it, which is the arrangement
+ * and not the chip.
+ *
+ * **The label truncates rather than wrapping, and the pill is capped at the
+ * width of its container.** A chip is read as one thing, and a chip that runs to
+ * three lines is a paragraph with a fill round it. Truncating costs the reader
+ * the tail of a long value, and the answer is the caller's: a value too long for
+ * a chip is a value that wants a `Table` cell or a `Tooltip` beside the pill
+ * rather than a pill with a smaller font.
+ *
+ * The clipping is on the label and not on the pill, which is a decision with a
+ * visible consequence. A pill that also carried `overflow-hidden` would cut the
+ * indicator of a control in the `trailing` slot in half, and the indicator gate
+ * cannot see that because it reads a class string and not a cascade. So the pill
+ * clips nothing, the label clips itself, and a control at either end draws its
+ * ring outside the fill where a reader can see all of it. This Component owns no
+ * indicator of its own because it renders nothing a reader can reach: the mark and
+ * the value are the caller's, and so is any control either of them turns out to
+ * be.
+ *
+ * **The tone defaults to `neutral` and every tone states its own ink.** The
+ * default is the tone for a value with nothing to say about it, which is the
+ * common case, and the pairs are the same pairs `tag-group` measures, so a pill
+ * never becomes unreadable by being moved onto another surface. The cost is
+ * visible: in a pack whose brand hue is its emphasis hue, an `info` pill and an
+ * emphasised mark are the same colour, and the words inside the pill are what
+ * separate them.
+ *
+ * **It draws no heading and no region.** A pill is a chip, and a chip is not a
+ * titled surface, so there is nothing here for `SectionHeading` to be right about
+ * and nothing to pass a `childLevel` to. A caller who needs the row to announce
+ * as a group writes the `role` and the name on their own element around it, which
+ * is the arrangement rather than the chip.
+ *
+ * It is a server Component: no hook, no state, no effect and no handler, so a
+ * page carrying two hundred pills ships no JavaScript at all. That is the whole
+ * reason it is a Component rather than a row inside `TagGroup`, and the cost it
+ * buys is the one on `trailing`: the pill cannot offer the affordance a caller
+ * most often wants, because offering it would mean shipping a handler and a
+ * client runtime for a chip.
+ */
+declare function Pill({ label, tone, size, leading, trailing, className, ...props }: PillProps): import("react").JSX.Element;
+export { Pill };
+//# sourceMappingURL=pill.d.ts.map

package/dist/components/ui/pill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pill.d.ts","sourceRoot":"","sources":["../../../src/components/ui/pill.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,CAAA;AAWjF;;;;;;;;;;GAUG;AACH,QAAA,MAAM,SAAS;;;;;;;;;CAGL,CAAA;AAEV,kCAAkC;AAClC,MAAM,MAAM,SAAS,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,GAAG;IACjE;;;;;;;;OAQG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAA;IACf;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,OAAO,SAAS,CAAA;IAC7B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,iBAAS,IAAI,CAAC,EACZ,KAAK,EACL,IAAgB,EAChB,IAAW,EACX,OAAO,EACP,QAAQ,EACR,SAAS,EACT,GAAG,KAAK,EACT,EAAE,SAAS,+BAuCX;AAED,OAAO,EAAE,IAAI,EAAE,CAAA"}

package/dist/components/ui/pill.js

@@ -0,0 +1,102 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from '../../lib/utils.js';
+/** The fill each tone is drawn in, from the semantic roles and no other. */
+const PILL_TONE = {
+    neutral: 'bg-secondary text-secondary-foreground border-transparent',
+    info: 'bg-brand-ink/10 text-foreground border-brand-ink/40',
+    success: 'bg-success text-success-foreground border-transparent',
+    warning: 'bg-warning text-warning-foreground border-transparent',
+    destructive: 'bg-destructive text-destructive-foreground border-transparent',
+};
+/**
+ * The two steps a pill is drawn at, as frame and label together.
+ *
+ * The pair moves as one because a pill whose label is set at one step and padded
+ * at the other is a chip with a hole in the middle of it: the extra leading
+ * reads as a mistake in the fill rather than as room for the label. `sm` is for a
+ * dense table row, a filter summary and a chart legend, and `md` is for a row a
+ * reader is meant to read. There is no third step because a chip set larger than
+ * `md` is a `Badge` at a different size and a `Badge` is the Component for a
+ * status the system decided.
+ */
+const PILL_SIZE = {
+    sm: { frame: 'gap-1 px-2 py-0.5 text-xs', label: 'font-medium' },
+    md: { frame: 'gap-1.5 px-2.5 py-1 text-sm', label: 'font-medium' },
+};
+/**
+ * One small fully rounded chip, holding one value, with a slot at each end.
+ *
+ * **It is not a `Tag`, and the two differences are both load bearing rather than
+ * cosmetic.** The first is the shape. A pill is fully rounded, and full rounding
+ * is the one radius a pack boundary is allowed to sit on, because
+ * `--radius-sm` through `--radius-4xl` are all computed from the pack's own
+ * `--radius` by multiplication: a `rounded-md` chip carrying a `data-pack`
+ * boundary is a chip whose corners move with its colour, and a row of six of them
+ * shows five different corner radii for one pack. `Tag` is a `rounded-md` chip
+ * because it is a chip in a running row, where a capsule per chip reads as a row
+ * of buttons, and a pill is a capsule because it is one value standing on its own
+ * and because the shape is the reason a `PackSwatch` and a pill can sit in the
+ * same row without one of them moving. The second is the two slots, which is
+ * where the cross of a `Tag` lives, and the argument for both is on `trailing`.
+ *
+ * **It is a single pill and not a group, and there is no `PillGroup` to be
+ * asked for later.** A set of values is `TagGroup`, which wraps, which labels
+ * itself, which owns the remove handler and which is a client Component the
+ * moment that handler is passed. A pill holds one value and the arrangement
+ * around it is the caller's, so a table cell, a chart legend, a summary line and
+ * a card header each get a pill and none of them gets a role or a heading nobody
+ * asked for. The cost is that a caller with six pills writes the row, and writes
+ * the gap and the wrap and the accessible name for it, which is the arrangement
+ * and not the chip.
+ *
+ * **The label truncates rather than wrapping, and the pill is capped at the
+ * width of its container.** A chip is read as one thing, and a chip that runs to
+ * three lines is a paragraph with a fill round it. Truncating costs the reader
+ * the tail of a long value, and the answer is the caller's: a value too long for
+ * a chip is a value that wants a `Table` cell or a `Tooltip` beside the pill
+ * rather than a pill with a smaller font.
+ *
+ * The clipping is on the label and not on the pill, which is a decision with a
+ * visible consequence. A pill that also carried `overflow-hidden` would cut the
+ * indicator of a control in the `trailing` slot in half, and the indicator gate
+ * cannot see that because it reads a class string and not a cascade. So the pill
+ * clips nothing, the label clips itself, and a control at either end draws its
+ * ring outside the fill where a reader can see all of it. This Component owns no
+ * indicator of its own because it renders nothing a reader can reach: the mark and
+ * the value are the caller's, and so is any control either of them turns out to
+ * be.
+ *
+ * **The tone defaults to `neutral` and every tone states its own ink.** The
+ * default is the tone for a value with nothing to say about it, which is the
+ * common case, and the pairs are the same pairs `tag-group` measures, so a pill
+ * never becomes unreadable by being moved onto another surface. The cost is
+ * visible: in a pack whose brand hue is its emphasis hue, an `info` pill and an
+ * emphasised mark are the same colour, and the words inside the pill are what
+ * separate them.
+ *
+ * **It draws no heading and no region.** A pill is a chip, and a chip is not a
+ * titled surface, so there is nothing here for `SectionHeading` to be right about
+ * and nothing to pass a `childLevel` to. A caller who needs the row to announce
+ * as a group writes the `role` and the name on their own element around it, which
+ * is the arrangement rather than the chip.
+ *
+ * It is a server Component: no hook, no state, no effect and no handler, so a
+ * page carrying two hundred pills ships no JavaScript at all. That is the whole
+ * reason it is a Component rather than a row inside `TagGroup`, and the cost it
+ * buys is the one on `trailing`: the pill cannot offer the affordance a caller
+ * most often wants, because offering it would mean shipping a handler and a
+ * client runtime for a chip.
+ */
+function Pill({ label, tone = 'neutral', size = 'md', leading, trailing, className, ...props }) {
+    const drawn = PILL_SIZE[size];
+    return (_jsxs("span", { "data-slot": "pill", "data-tone": tone, className: cn('inline-flex max-w-full items-center rounded-full border', drawn.frame, PILL_TONE[tone], className), ...props, children: [leading === undefined || leading === null || leading === false ? null : (
+            /*
+             * The leading slot, and it does not give way. A mark that is squeezed is a
+             * mark that no longer reads, so both slots are `shrink-0` and the label is
+             * the part that gives way: it is the only thing here whose content can be
+             * abbreviated, and a mark a reader cannot recognise is worse than a value
+             * whose tail is cut.
+             */
+            _jsx("span", { "data-slot": "pill-leading", className: "flex shrink-0 items-center", children: leading })), _jsx("span", { "data-slot": "pill-label", className: cn('min-w-0 truncate', drawn.label), children: label }), trailing === undefined || trailing === null || trailing === false ? null : (_jsx("span", { "data-slot": "pill-trailing", className: "flex shrink-0 items-center", children: trailing }))] }));
+}
+export { Pill };

package/dist/components/ui/platform-modifier-key.d.ts

@@ -0,0 +1,129 @@
+/**
+ * The four concrete modifier keys a chord can name.
+ *
+ * Closed on purpose. `mod` is deliberately not a member: it is not a key, it is a
+ * name for whichever of these two the host uses for its command chord, and
+ * collapsing it into the set is what would let a caller write a label for it and
+ * have that label be wrong on half the platforms.
+ */
+export type PlatformModifierKeyName = 'alt' | 'ctrl' | 'meta' | 'shift';
+/**
+ * What a chord may ask for, which is the four keys plus `mod`.
+ *
+ * `mod` is the one that cannot be resolved by reading a string. It is the modifier
+ * a product writes in its own documentation as "the command key", and it is `meta`
+ * on a machine running macOS and `ctrl` everywhere else. A caller who has to branch
+ * on the platform to label it has been handed a detector, and a detector in four
+ * consumer repositories is four detectors that will disagree.
+ */
+export type PlatformModifier = PlatformModifierKeyName | 'mod';
+/** A keyboard chord: the key, and which modifiers it travels with. */
+export interface PlatformChord {
+    /**
+     * The non-modifier key of the chord.
+     *
+     * The caller's own string, printed as given apart from a single character, which is
+     * drawn in upper case. Every convention for writing a shortcut writes a letter in
+     * upper case, so `⌘k` reads as a typo to every reader who meets it, and Prism
+     * resolves that one case rather than leaving it to four call sites. Any longer key
+     * is left exactly as passed, because the capitalisation of a word such as the name
+     * of a function key is the product's own choice and not a fact about a keyboard.
+     *
+     * A caller reading this off a `KeyboardEvent` should pass the event's own `key`
+     * member, upper-cased, because that string is what the platform reports rather
+     * than what a product writes.
+     */
+    key: string;
+    /**
+     * The modifiers the chord travels with, in any order.
+     *
+     * Optional and empty by default, because most chords have none, and a required
+     * empty array on every call site is noise about the common case. The Component
+     * draws them in one canonical order whatever order they arrive in, because a
+     * shortcut whose modifiers change position between two menus is a shortcut a
+     * reader has to read twice.
+     */
+    modifiers?: readonly PlatformModifier[];
+}
+/** The props the Platform modifier key accepts. */
+export interface PlatformModifierKeyProps {
+    /** The chord to draw. */
+    chord: PlatformChord;
+    /**
+     * The name of each of the four modifier keys, in the reader's own words or in the
+     * glyphs their platform uses.
+     *
+     * Required and complete rather than partial, and this is the whole reason the
+     * Component is not a `Kbd` with a different string. A glyph has no English name:
+     * the command key is a symbol on one platform and two letters on another, and the
+     * letters are localised like any other word. So Prism holds no glyph and no word
+     * at all here, and a product that ships in German writes four German words, a
+     * product that ships only on macOS writes four symbols, and a product that ships
+     * on both writes the symbol for the Mac and the word for everywhere else. The
+     * cost of a complete record is that a caller who shows one shortcut still writes
+     * four names; that is cheaper than the alternative, which is four call sites that
+     * each remember to localise one of them.
+     */
+    labels: Record<PlatformModifierKeyName, string>;
+    /** Layout only. */
+    className?: string;
+}
+/**
+ * The modifier glyphs of a keyboard chord, resolved for the reader's own platform.
+ *
+ * **This is behaviour, not a label, and that is why it is a Client Component.** The
+ * platform is a fact about the machine and not about the document, so the glyph for
+ * a chord cannot be chosen at the call site and passed down as a string: a caller
+ * that resolved it would have to read the platform itself, and would have to read it
+ * in every one of the surfaces that show a shortcut, which is four repositories
+ * holding four copies of a detector that will drift. The consumer hands over a chord
+ * as the platform reports it, and this Component owns the one lookup.
+ *
+ * **And it is not `Kbd` with a different string.** `Kbd` answers one question: draw
+ * this key. Its caller already knows which key, and the string it prints is the key.
+ * The differences that matter here:
+ *
+ *  - the glyph is chosen at runtime from the host, not supplied by the caller;
+ *  - `labels` is a complete record of the four modifier names rather than the text
+ *    of one element, because a command chord is several keys and each of them has a
+ *    name the reader's language and platform decide;
+ *  - the modifiers are ordered, deduplicated and resolved, so a caller may pass them
+ *    in whatever order its data holds and the printed chord is the same chord;
+ *  - the frame before the platform is known is drawn deliberately rather than left
+ *    to chance, which is the next paragraph and is the cost of being a client
+ *    Component at all.
+ *
+ * **What is drawn before the platform is known, and why.** A server render cannot
+ * read `navigator`, and hydration cannot run before the first paint, so the first
+ * frame is drawn with the host unknown. Every slot that does not depend on the host
+ * is drawn normally: the concrete modifiers, the key, and their order. The one slot
+ * that cannot be drawn is `mod`, because choosing between the caller's `meta` label
+ * and the caller's `ctrl` label is precisely the question the server cannot answer.
+ * **So the `mod` slot renders as an empty `Kbd`: the authored key box, with nothing
+ * in it, occupying the space the glyph will take.** Three consequences, stated rather
+ * than discovered. The row never shows a glyph that might be wrong, which is the one
+ * outcome not available to any other choice here, because guessing means half the
+ * readers are told their own keyboard is something else. No reader ever sees a
+ * placeholder character such as a question mark, which would be read aloud by a
+ * screen reader as part of the shortcut. And the layout does not jump, because the
+ * box was always there; on a host whose labels are words rather than symbols the row
+ * still widens once by that word's width, since an empty box is the minimum key width
+ * and a word is wider, and a consumer whose layout cannot tolerate one frame of that
+ * should render the shortcut client-side or hold the width open beside it. Everything
+ * else in the chord is correct in that frame, so the shortest case is one empty box
+ * next to a correct key.
+ *
+ * **The host cannot change while the page is open**, so the detector runs once in an
+ * effect rather than being subscribed to. A reader does not move a browser from
+ * Windows to macOS, and a subscription would be a listener with nothing to report
+ * for the life of the document.
+ *
+ * The whole chord is announced as its glyphs, in order, which is how a shortcut is
+ * read in every tool that documents one. A caller whose labels do not survive being
+ * read aloud, which is the usual objection to a symbol such as the command glyph,
+ * answers it in the place the map already exists: put words in `labels` for that
+ * platform.
+ */
+declare function PlatformModifierKey({ chord, labels, className }: PlatformModifierKeyProps): import("react").JSX.Element;
+export { PlatformModifierKey };
+//# sourceMappingURL=platform-modifier-key.d.ts.map

package/dist/components/ui/platform-modifier-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-modifier-key.d.ts","sourceRoot":"","sources":["../../../src/components/ui/platform-modifier-key.tsx"],"names":[],"mappings":"AAOA;;;;;;;GAOG;AACH,MAAM,MAAM,uBAAuB,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAEvE;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG,uBAAuB,GAAG,KAAK,CAAA;AAE9D,sEAAsE;AACtE,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;;;OAaG;IACH,GAAG,EAAE,MAAM,CAAA;IACX;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAA;CACxC;AAED,mDAAmD;AACnD,MAAM,WAAW,wBAAwB;IACvC,yBAAyB;IACzB,KAAK,EAAE,aAAa,CAAA;IACpB;;;;;;;;;;;;;;OAcG;IACH,MAAM,EAAE,MAAM,CAAC,uBAAuB,EAAE,MAAM,CAAC,CAAA;IAC/C,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAsDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,iBAAS,mBAAmB,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,wBAAwB,+BAiClF;AAED,OAAO,EAAE,mBAAmB,EAAE,CAAA"}

package/dist/components/ui/platform-modifier-key.js

@@ -0,0 +1,125 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { Kbd } from './kbd.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * Where a modifier sits in the printed chord.
+ *
+ * One order for every platform rather than one per platform, because the two
+ * conventions agree: a Windows chord reads Ctrl, Alt, Shift, Win and a macOS chord
+ * reads the same four in the same sequence. Branching the order on the host would
+ * buy nothing and would make the Component's output depend on a second runtime fact
+ * for no reader-visible gain.
+ *
+ * `mod` sits where `ctrl` sits because that is what it is on a host that is not an
+ * Apple one, and the two share a rank so a chord carrying both prints them in the
+ * order the caller supplied them, which is the only order that can be right when the
+ * caller asked for a chord that is arguably two spellings of one key.
+ */
+const MODIFIER_ORDER = {
+    mod: 0,
+    ctrl: 0,
+    alt: 1,
+    shift: 2,
+    meta: 3,
+};
+/** The platforms whose command key is `meta`. */
+const APPLE = /mac|iphone|ipad|ipod/i;
+/**
+ * Whether the host machine uses `meta` for its command chord.
+ *
+ * A detector rather than a string comparison on `navigator.platform` alone, because
+ * that member is deprecated and a consumer cannot fix it from here: the
+ * `userAgentData` hint is preferred where a browser publishes it and the older
+ * member is the fallback, and both are read rather than parsed by this package
+ * beyond the one question this Component asks.
+ */
+function hostUsesMeta() {
+    if (typeof navigator === 'undefined')
+        return false;
+    const hinted = navigator
+        .userAgentData;
+    const platform = hinted?.platform ?? navigator.platform ?? '';
+    return APPLE.test(platform);
+}
+/** The concrete key a requested modifier is on this host. */
+function resolve(modifier, apple) {
+    return modifier === 'mod' ? (apple ? 'meta' : 'ctrl') : modifier;
+}
+/** A single-character key is drawn in upper case; anything else is left as passed. */
+function displayKey(key) {
+    return key.length === 1 ? key.toUpperCase() : key;
+}
+/**
+ * The modifier glyphs of a keyboard chord, resolved for the reader's own platform.
+ *
+ * **This is behaviour, not a label, and that is why it is a Client Component.** The
+ * platform is a fact about the machine and not about the document, so the glyph for
+ * a chord cannot be chosen at the call site and passed down as a string: a caller
+ * that resolved it would have to read the platform itself, and would have to read it
+ * in every one of the surfaces that show a shortcut, which is four repositories
+ * holding four copies of a detector that will drift. The consumer hands over a chord
+ * as the platform reports it, and this Component owns the one lookup.
+ *
+ * **And it is not `Kbd` with a different string.** `Kbd` answers one question: draw
+ * this key. Its caller already knows which key, and the string it prints is the key.
+ * The differences that matter here:
+ *
+ *  - the glyph is chosen at runtime from the host, not supplied by the caller;
+ *  - `labels` is a complete record of the four modifier names rather than the text
+ *    of one element, because a command chord is several keys and each of them has a
+ *    name the reader's language and platform decide;
+ *  - the modifiers are ordered, deduplicated and resolved, so a caller may pass them
+ *    in whatever order its data holds and the printed chord is the same chord;
+ *  - the frame before the platform is known is drawn deliberately rather than left
+ *    to chance, which is the next paragraph and is the cost of being a client
+ *    Component at all.
+ *
+ * **What is drawn before the platform is known, and why.** A server render cannot
+ * read `navigator`, and hydration cannot run before the first paint, so the first
+ * frame is drawn with the host unknown. Every slot that does not depend on the host
+ * is drawn normally: the concrete modifiers, the key, and their order. The one slot
+ * that cannot be drawn is `mod`, because choosing between the caller's `meta` label
+ * and the caller's `ctrl` label is precisely the question the server cannot answer.
+ * **So the `mod` slot renders as an empty `Kbd`: the authored key box, with nothing
+ * in it, occupying the space the glyph will take.** Three consequences, stated rather
+ * than discovered. The row never shows a glyph that might be wrong, which is the one
+ * outcome not available to any other choice here, because guessing means half the
+ * readers are told their own keyboard is something else. No reader ever sees a
+ * placeholder character such as a question mark, which would be read aloud by a
+ * screen reader as part of the shortcut. And the layout does not jump, because the
+ * box was always there; on a host whose labels are words rather than symbols the row
+ * still widens once by that word's width, since an empty box is the minimum key width
+ * and a word is wider, and a consumer whose layout cannot tolerate one frame of that
+ * should render the shortcut client-side or hold the width open beside it. Everything
+ * else in the chord is correct in that frame, so the shortest case is one empty box
+ * next to a correct key.
+ *
+ * **The host cannot change while the page is open**, so the detector runs once in an
+ * effect rather than being subscribed to. A reader does not move a browser from
+ * Windows to macOS, and a subscription would be a listener with nothing to report
+ * for the life of the document.
+ *
+ * The whole chord is announced as its glyphs, in order, which is how a shortcut is
+ * read in every tool that documents one. A caller whose labels do not survive being
+ * read aloud, which is the usual objection to a symbol such as the command glyph,
+ * answers it in the place the map already exists: put words in `labels` for that
+ * platform.
+ */
+function PlatformModifierKey({ chord, labels, className }) {
+    // `null` is the third state and it is the load-bearing one: it is the server frame
+    // and the hydration frame, and it is distinct from a resolved `false` so the frame
+    // can draw a slot as unknown rather than as a host that answered no.
+    const [apple, setApple] = useState(null);
+    useEffect(() => {
+        setApple(hostUsesMeta());
+    }, []);
+    const known = apple !== null;
+    const modifiers = Array.from(new Set(chord.modifiers ?? [])).sort((a, b) => MODIFIER_ORDER[a] - MODIFIER_ORDER[b]);
+    return (_jsxs("span", { "data-slot": "platform-modifier-key", "data-host": known ? (apple === true ? 'apple' : 'other') : 'unknown', className: cn('inline-flex items-center gap-1', className), children: [modifiers.map((modifier) => modifier === 'mod' && !known ? (
+            // The reserved slot: the authored key box with nothing in it, so the row
+            // holds its shape and no reader is shown a glyph that may be wrong.
+            _jsx(Kbd, { "data-resolved": "false" }, modifier)) : (_jsx(Kbd, { children: labels[resolve(modifier, apple === true)] }, modifier))), _jsx(Kbd, { children: displayKey(chord.key) })] }));
+}
+export { PlatformModifierKey };

package/dist/components/ui/popover.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"popover.d.ts","sourceRoot":"","sources":["../../../src/components/ui/popover.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAI3C;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,iCAAiC;IACjC,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,6DAA6D;IAC7D,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,0CAA0C;IAC1C,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACtC,4EAA4E;IAC5E,KAAK,CAAC,EAAE,OAAO,GAAG,YAAY,CAAA;IAC9B,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAC3B;AAED,oDAAoD;AACpD,MAAM,WAAW,mBAAoB,SAAQ,cAAc,CAAC,QAAQ,CAAC;IACnE,iEAAiE;IACjE,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAoB,SAAQ,cAAc,CAAC,KAAK,CAAC;IAChE,+EAA+E;IAC/E,IAAI,CAAC,EAAE,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAA;IAC1C,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAA;IAClC,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,qEAAqE;IACrE,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;GAQG;AACH,iBAAS,OAAO,CAAC,EAAE,GAAG,KAAK,EAAE,EAAE,YAAY,+BAE1C;AAED,0CAA0C;AAC1C,iBAAS,cAAc,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,mBAAmB,+BAcnE;AAED,oCAAoC;AACpC,iBAAS,cAAc,CAAC,EACtB,SAAS,EACT,IAAe,EACf,KAAgB,EAChB,UAAc,EACd,WAAe,EACf,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,mBAAmB,+BA0BrB;AAED,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,CAAA"}
+{"version":3,"file":"popover.d.ts","sourceRoot":"","sources":["../../../src/components/ui/popover.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAI3C;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,iCAAiC;IACjC,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,6DAA6D;IAC7D,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,0CAA0C;IAC1C,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACtC,4EAA4E;IAC5E,KAAK,CAAC,EAAE,OAAO,GAAG,YAAY,CAAA;IAC9B,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAC3B;AAED,oDAAoD;AACpD,MAAM,WAAW,mBAAoB,SAAQ,cAAc,CAAC,QAAQ,CAAC;IACnE,iEAAiE;IACjE,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAoB,SAAQ,cAAc,CAAC,KAAK,CAAC;IAChE,+EAA+E;IAC/E,IAAI,CAAC,EAAE,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAA;IAC1C,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAA;IAClC,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,qEAAqE;IACrE,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;GAQG;AACH,iBAAS,OAAO,CAAC,EAAE,GAAG,KAAK,EAAE,EAAE,YAAY,+BAE1C;AAED,0CAA0C;AAC1C,iBAAS,cAAc,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,mBAAmB,+BAqBnE;AAED,oCAAoC;AACpC,iBAAS,cAAc,CAAC,EACtB,SAAS,EACT,IAAe,EACf,KAAgB,EAChB,UAAc,EACd,WAAe,EACf,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,mBAAmB,+BA0BrB;AAED,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,CAAA"}

package/dist/components/ui/popover.js

@@ -16,7 +16,14 @@ function Popover({ ...props }) {
 }
 /** The element that opens the popover. */
 function PopoverTrigger({ className, ...props }) {
-    return (_jsx(PopoverPrimitive.Trigger, { "data-slot": "popover-trigger", className: cn('bg-background shadow-xs inline-flex h-9 items-center justify-center gap-2 rounded-md border px-3 text-sm font-medium outline-none', 'transition-[color,box-shadow,background-color] duration-fast ease-out', 'hover:bg-accent hover:text-accent-foreground focus-visible:border-ring focus-visible:ring-ring focus-visible:ring-[3px]', 'disabled:pointer-events-none disabled:opacity-50', className), ...props }));
+    return (_jsx(PopoverPrimitive.Trigger, { "data-slot": "popover-trigger", className: cn('bg-background shadow-xs inline-flex h-9 items-center justify-center gap-2 rounded-md border px-3 text-sm font-medium outline-none', 'transition-[color,box-shadow,background-color] duration-fast ease-out', 'hover:bg-accent hover:text-accent-foreground focus-visible:border-ring focus-visible:ring-ring focus-visible:ring-[3px]', 'disabled:pointer-events-none disabled:opacity-50', 
+        // The coarse-pointer floor, as a step. This is the same string
+        // `dropdown-menu.tsx` and `alert-dialog.tsx` draw on their triggers, and a
+        // trigger that opens a popup is a button: 36 tall, content wide, beside
+        // whatever else the caller put in the row. A band would overhang a trigger the
+        // caller sized themselves, which is the reason `DESIGN.md` reserves bands for
+        // a shape whose drawn size the design owns. See The coarse-pointer floor.
+        'pointer-coarse:h-11', className), ...props }));
 }
 /** The floating popover surface. */
 function PopoverContent({ className, side = 'bottom', align = 'center', sideOffset = 4, alignOffset = 0, children, ...props }) {