@sincpro/web-ui 0.0.0-stage → 0.1.0

package/dist/primitives/field/Suggest.d.ts

@@ -0,0 +1,48 @@
+import { type FormMode } from "./mode.js";
+/**
+ * A text with suggestions: the open field that proposes.
+ *
+ * Context: there were two text controls and neither served the most common case of an ERP
+ * form. `Select` is a CLOSED list —what is not there cannot be written— and `TextInput` is
+ * free but does not help. The unit of a product, the bank of a payment, the city of a
+ * customer: fields where values already exist and they have to be offered **without
+ * forbidding a new one**.
+ *
+ * What not having it costs shows in the data: without suggestions «Bs.», «BOB» and
+ * «bolivianos» end up in the same column, and then somebody writes a `CASE` to unify them.
+ *
+ * ── Why it is not a `<datalist>` ────────────────────────────────────
+ *
+ * Because every browser draws it its own way and none follows the tokens: in the middle of a
+ * form with the system's type, radius and colors, an operating-system dropdown appears. It is
+ * React Aria's `ComboBox` with `allowsCustomValue` instead: the list floats on the system's
+ * `Popover`, the keyboard is a combobox's (arrows move, Enter picks, Escape closes), and
+ * whatever is typed stays typed. The filter is React Aria's `contains` in the copy's locale,
+ * so «potosi» finds «Potosí».
+ *
+ * ── What it is NOT ──────────────────────────────────────────────────
+ *
+ * It is not `ComboBox`, whose value must be one of its options, nor `Picker`, which chooses
+ * ONE record among thousands with its own search, metadata rows and dialog. This is a text
+ * field that also proposes: the list is short, it is of values and not of records, and what
+ * is stored is what was written.
+ */
+export type SuggestProps = {
+    id?: string;
+    value: string;
+    onChange?: (next: string) => void;
+    /** What already exists. Short: if they are hundreds, what is needed is a `Picker`. */
+    suggestions: readonly string[];
+    placeholder?: string;
+    describedBy?: string;
+    invalid?: boolean;
+    disabled?: boolean;
+    mono?: boolean;
+    mode?: FormMode;
+    /** How many are shown at once. More than this is a list to be read, and reading a list
+     *  is what this control exists to avoid. */
+    max?: number;
+    /** The name of the field when it is not inside a `Field`. */
+    "aria-label"?: string;
+};
+export declare function Suggest({ mode, ...props }: SuggestProps): import("react").JSX.Element;

package/dist/primitives/field/Suggest.js

@@ -0,0 +1,43 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { AriaLocale } from "../../foundations/aria.js";
+import { FieldGroup, listOptionStyles } from "./aria.js";
+import { useFieldIds } from "./context.js";
+import { ReadValue } from "./Field.js";
+import { useFormMode } from "./mode.js";
+import { Popover } from "../overlay/Popover.js";
+import { ComboBox as AriaComboBox, Input, ListBox, ListBoxItem, useFilter, } from "react-aria-components";
+const MAX = 8;
+export function Suggest({ mode, ...props }) {
+    if (useFormMode(mode) === "read")
+        return _jsx(ReadValue, { value: props.value, mono: props.mono });
+    /* The filter reads the locale from React Aria's context, so the box that provides it has
+       to be ABOVE the component that asks for it. */
+    return (_jsx(AriaLocale, { children: _jsx(EditableSuggest, { ...props }) }));
+}
+function EditableSuggest({ id: ownId, value, onChange, suggestions, placeholder, describedBy: ownDescribedBy, invalid: ownInvalid, disabled = false, mono = false, max = MAX, "aria-label": ariaLabel, }) {
+    const { id, labelledBy, describedBy, invalid } = useFieldIds({
+        id: ownId,
+        describedBy: ownDescribedBy,
+        invalid: ownInvalid,
+    });
+    const { contains } = useFilter({ sensitivity: "base" });
+    /* Filtered by what is typed, hiding the one that ALREADY is exactly the value: offering
+       what someone just finished typing is a suggestion that suggests nothing. The list is
+       filtered here and not by React Aria because of that rule and of `max`. */
+    const needle = value.trim();
+    /* «Exactly» ignores case but NOT accents: «potosi» still offers «Potosí», which is the
+       spelling the person was reaching for. */
+    const exact = needle.toLocaleLowerCase();
+    const shown = suggestions
+        .filter((one) => one.toLocaleLowerCase() !== exact)
+        .filter((one) => needle === "" || contains(one, needle))
+        .slice(0, max)
+        .map((one) => ({ id: one }));
+    return (_jsxs(AriaComboBox, { id: id, "aria-labelledby": labelledBy, "aria-label": labelledBy === undefined ? (ariaLabel ?? placeholder) : ariaLabel, 
+        /* An open field: what is typed is the value, a suggestion only fills it faster. */
+        allowsCustomValue: true, inputValue: value, onInputChange: (next) => onChange?.(next), items: shown, 
+        /* It proposes as soon as the field is entered, like the hand-written one did: the
+           suggestions are most useful BEFORE anything is typed. */
+        menuTrigger: "focus", isInvalid: invalid, isDisabled: disabled, className: "w-full min-w-0", children: [_jsx(FieldGroup, { children: _jsx(Input, { "aria-describedby": describedBy, placeholder: placeholder, className: `h-full min-w-0 flex-1 bg-transparent px-2.5 text-meta text-ink outline-0 placeholder:text-muted disabled:cursor-not-allowed ${mono ? "font-mono" : ""}` }) }), _jsx(Popover, { placement: "bottom start", className: "w-(--trigger-width)", children: _jsx(ListBox, { className: "max-h-[inherit] overflow-auto p-1 outline-0", children: (item) => (_jsx(ListBoxItem, { id: item.id, textValue: item.id, className: listOptionStyles, children: _jsx("span", { className: `min-w-0 truncate ${mono ? "font-mono" : ""}`, children: item.id }) })) }) })] }));
+}

package/dist/primitives/field/aria.d.ts

@@ -0,0 +1,61 @@
+import { composeClasses } from "../../foundations/variants.js";
+import type { Ref } from "react";
+import { type ButtonProps as AriaButtonProps, type GroupProps } from "react-aria-components";
+/**
+ * The pieces every React Aria control of the system is built from — the box a date field,
+ * a combobox or a number field draws, and the small button inside it.
+ *
+ * Context: they look exactly like `controlClasses()` — same height, border, radius and
+ * focus — because a form mixes both kinds of control in one column, and a date field one
+ * pixel taller than the text input above it is the first thing an eye catches.
+ */
+export declare const fieldGroupStyles: import("tailwind-variants/config").TVReturnType<{
+    isFocusWithin: {
+        false: string;
+        true: string;
+    };
+    isInvalid: {
+        true: string;
+    };
+    isDisabled: {
+        true: string;
+    };
+}, undefined, "group flex h-(--size-control-md) w-full min-w-0 items-center overflow-hidden rounded-control border bg-surface text-meta text-ink transition-colors duration-(--duration-instant) forced-colors:bg-[Field]", {
+    isFocusVisible: {
+        false: string;
+        true: string;
+    };
+}, undefined, import("tailwind-variants/config").TVReturnType<{
+    isFocusVisible: {
+        false: string;
+        true: string;
+    };
+}, undefined, "outline-primary outline-offset-2 forced-colors:outline-[Highlight]", undefined, undefined, undefined>>;
+/** The box of a composite control: a field and its buttons, framed as one input. The `ref`
+ *  reaches the box (React 19: a plain prop) — a control that floats a list as wide as the
+ *  box, like `TagsField`, measures it. */
+export declare function FieldGroup({ ref, ...props }: GroupProps & {
+    ref?: Ref<HTMLDivElement>;
+}): import("react").JSX.Element;
+/** The button inside a field: the calendar of a date picker, the arrow of a combobox. */
+export declare function FieldButton(props: AriaButtonProps): import("react").JSX.Element;
+/**
+ * One row of a floating list — the options of a `Select`, the suggestions of a `Suggest`.
+ *
+ * Context: the same row `ComboBox` draws (control height, the `primary` tint on the row the
+ * keyboard is on), so every list that drops from a field reads as one kind of thing whatever
+ * control opened it.
+ */
+export declare const listOptionStyles: import("tailwind-variants/config").TVReturnType<{
+    isFocused: {
+        true: string;
+    };
+    isPressed: {
+        true: string;
+    };
+    isDisabled: {
+        true: string;
+    };
+}, undefined, "group flex min-h-(--size-control-md) cursor-default items-center gap-2 rounded-control px-2 py-1 text-meta text-ink outline-0 select-none forced-color-adjust-none", undefined, undefined, undefined>;
+/** For a control that only adds to the system's classes. */
+export { composeClasses };

package/dist/primitives/field/aria.js

@@ -0,0 +1,70 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { composeClasses, focusRing, tv } from "../../foundations/variants.js";
+import { Button as AriaButton, composeRenderProps, Group, } from "react-aria-components";
+/**
+ * The pieces every React Aria control of the system is built from — the box a date field,
+ * a combobox or a number field draws, and the small button inside it.
+ *
+ * Context: they look exactly like `controlClasses()` — same height, border, radius and
+ * focus — because a form mixes both kinds of control in one column, and a date field one
+ * pixel taller than the text input above it is the first thing an eye catches.
+ */
+export const fieldGroupStyles = tv({
+    extend: focusRing,
+    base: "group flex h-(--size-control-md) w-full min-w-0 items-center overflow-hidden rounded-control border bg-surface text-meta text-ink transition-colors duration-(--duration-instant) forced-colors:bg-[Field]",
+    variants: {
+        isFocusWithin: {
+            false: "border-line-strong forced-colors:border-[ButtonBorder]",
+            true: "border-primary forced-colors:border-[Highlight]",
+        },
+        isInvalid: {
+            true: "border-danger forced-colors:border-[Mark]",
+        },
+        isDisabled: {
+            true: "cursor-not-allowed bg-ground text-muted forced-colors:border-[GrayText]",
+        },
+    },
+});
+/** The box of a composite control: a field and its buttons, framed as one input. The `ref`
+ *  reaches the box (React 19: a plain prop) — a control that floats a list as wide as the
+ *  box, like `TagsField`, measures it. */
+export function FieldGroup({ ref, ...props }) {
+    return (_jsx(Group, { ref: ref, ...props, className: composeRenderProps(props.className, (className, state) => fieldGroupStyles({ ...state, className })) }));
+}
+const fieldButton = tv({
+    extend: focusRing,
+    base: "inline-flex shrink-0 items-center justify-center rounded-mark p-1 text-muted transition-colors duration-(--duration-instant) hover:bg-ink/6 hover:text-ink pressed:bg-ink/10",
+    variants: {
+        isDisabled: {
+            true: "text-line-strong hover:bg-transparent forced-colors:text-[GrayText]",
+        },
+    },
+});
+/** The button inside a field: the calendar of a date picker, the arrow of a combobox. */
+export function FieldButton(props) {
+    return (_jsx(AriaButton, { ...props, className: composeRenderProps(props.className, (className, state) => fieldButton({ ...state, className })) }));
+}
+/**
+ * One row of a floating list — the options of a `Select`, the suggestions of a `Suggest`.
+ *
+ * Context: the same row `ComboBox` draws (control height, the `primary` tint on the row the
+ * keyboard is on), so every list that drops from a field reads as one kind of thing whatever
+ * control opened it.
+ */
+export const listOptionStyles = tv({
+    base: "group flex min-h-(--size-control-md) cursor-default items-center gap-2 rounded-control px-2 py-1 text-meta text-ink outline-0 select-none forced-color-adjust-none",
+    variants: {
+        isFocused: {
+            true: "bg-primary/8 forced-colors:bg-[Highlight] forced-colors:text-[HighlightText]",
+        },
+        isPressed: {
+            true: "bg-primary/12",
+        },
+        isDisabled: {
+            true: "text-muted opacity-45 forced-colors:text-[GrayText]",
+        },
+    },
+});
+/** For a control that only adds to the system's classes. */
+export { composeClasses };

package/dist/primitives/field/context.d.ts

@@ -0,0 +1,30 @@
+/**
+ * What a `Field` hands to the control inside it: the id its label points at, the ids that
+ * describe it (hint, error), and whether it is in error.
+ *
+ * Context: `Field` used to hand these through a render prop — `{(aria) => <TextInput
+ * id={aria.id} … />}` — on every field of every form. Correct, and three lines of wiring
+ * per field that anyone could get wrong (forget `describedBy` and the error is never read
+ * aloud). Now a control written directly inside a `Field` reads them from here; the render
+ * prop still works, and an explicit prop on the control always wins.
+ */
+export type FieldIds = {
+    id: string;
+    /** The id of the field's label. A native input is named by `<label for>`; a React Aria
+     *  control — a date picker, a combobox — is a group of elements, and is named by this. */
+    labelId: string;
+    describedBy: string | undefined;
+    invalid: boolean;
+};
+export declare const FieldIdsContext: import("react").Context<FieldIds | null>;
+/** The ids of the enclosing `Field`, resolved against the control's own props. */
+export declare function useFieldIds(own: {
+    id?: string;
+    describedBy?: string;
+    invalid?: boolean;
+}): {
+    id: string | undefined;
+    labelledBy: string | undefined;
+    describedBy: string | undefined;
+    invalid: boolean;
+};

package/dist/primitives/field/context.js

@@ -0,0 +1,13 @@
+"use client";
+import { createContext, useContext } from "react";
+export const FieldIdsContext = createContext(null);
+/** The ids of the enclosing `Field`, resolved against the control's own props. */
+export function useFieldIds(own) {
+    const field = useContext(FieldIdsContext);
+    return {
+        id: own.id ?? field?.id,
+        labelledBy: field?.labelId,
+        describedBy: own.describedBy ?? field?.describedBy,
+        invalid: own.invalid ?? field?.invalid ?? false,
+    };
+}

package/dist/primitives/field/index.d.ts

@@ -0,0 +1,7 @@
+export { Checkbox, type CheckItem, CheckList } from "./Checks.js";
+export { type FieldIds, useFieldIds } from "./context.js";
+export { DropZone, type DropZoneProps } from "./DropZone.js";
+export { controlClasses, DataField, Field, NumberInput, ReadValue, Select, type SelectOption, TextArea, TextInput, } from "./Field.js";
+export { type FieldLayout, FieldLayoutProvider, useSheetLayout, } from "./layout.js";
+export { type FormMode, FormModeProvider, useFormMode, } from "./mode.js";
+export { Suggest, type SuggestProps } from "./Suggest.js";

package/dist/primitives/field/index.js

@@ -0,0 +1,11 @@
+/* THE CONTROLS a form is written with.
+   What ARRANGES them —the sheet, the section, the footer— lives in `components/form`: a
+   control does not know a form exists, and is used the same way inside a cell, a filter or
+   a dialog. */
+export { Checkbox, CheckList } from "./Checks.js";
+export { useFieldIds } from "./context.js";
+export { DropZone } from "./DropZone.js";
+export { controlClasses, DataField, Field, NumberInput, ReadValue, Select, TextArea, TextInput, } from "./Field.js";
+export { FieldLayoutProvider, useSheetLayout, } from "./layout.js";
+export { FormModeProvider, useFormMode, } from "./mode.js";
+export { Suggest } from "./Suggest.js";

package/dist/primitives/field/layout.d.ts

@@ -0,0 +1,24 @@
+import { type ReactNode } from "react";
+/**
+ * HOW A FIELD PLACES ITS LABEL. Declared once, inherited by every field.
+ *
+ *     stacked      the label above. The grouped look of iOS. The default.
+ *     horizontal   label | value, and every value starts on the same vertical — the Odoo
+ *                  form, where twenty fields read as a column and not as a bounce.
+ *
+ * Context: it lives in `primitives/field` and not next to `Sheet`, which declares it,
+ * because the one that READS it is `Field` — and a primitive cannot import from a
+ * component. The container sets it, the field obeys, and the type that joins them is in the
+ * level both can see.
+ *
+ * Being a context and not a prop is what keeps a sheet from ending up half aligned: nobody
+ * has to remember to pass it to each field.
+ */
+export type FieldLayout = "stacked" | "horizontal";
+/** The name the sheet knows it by. */
+export type SheetLayout = FieldLayout;
+export declare function useSheetLayout(): FieldLayout;
+export declare function FieldLayoutProvider({ value, children, }: {
+    value: FieldLayout;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/primitives/field/layout.js

@@ -0,0 +1,10 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+const LayoutCtx = createContext("stacked");
+export function useSheetLayout() {
+    return useContext(LayoutCtx);
+}
+export function FieldLayoutProvider({ value, children, }) {
+    return _jsx(LayoutCtx.Provider, { value: value, children: children });
+}

package/dist/primitives/field/mode.d.ts

@@ -0,0 +1,9 @@
+import { type ReactNode } from "react";
+export type FormMode = "edit" | "read";
+export declare function FormModeProvider({ value, children, }: {
+    value: FormMode;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** The mode of this field. The prop beats the context — a computed field stays
+ *  in read mode inside a form that is being edited. */
+export declare function useFormMode(explicit?: FormMode): FormMode;

package/dist/primitives/field/mode.js

@@ -0,0 +1,13 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+const Ctx = createContext("edit");
+export function FormModeProvider({ value, children, }) {
+    return _jsx(Ctx.Provider, { value: value, children: children });
+}
+/** The mode of this field. The prop beats the context — a computed field stays
+ *  in read mode inside a form that is being edited. */
+export function useFormMode(explicit) {
+    const inherited = useContext(Ctx);
+    return explicit ?? inherited;
+}

package/dist/primitives/hint/Hint.d.ts

@@ -0,0 +1,31 @@
+import { type ReactNode } from "react";
+/**
+ * A sentence that does not fit on the page, attached to a mark.
+ *
+ * Context: `title` on a field is a native tooltip and nobody finds it. Odoo
+ * puts a `?` next to the label; pressing it is how you read the help without
+ * it eating a line. The mark is the affordance; the sentence is the content.
+ *
+ * ── Why a click and a popover, and not a `Tooltip` ──
+ *
+ * A `Tooltip` is a LABEL: a few words that show on hover and vanish when the
+ * pointer leaves — useless on a tablet, and gone before a sentence is read.
+ * This is content, so it opens on press (mouse, touch, Enter or Space) and
+ * stays until it is put away: a second press, Escape, or a click outside. It
+ * is React Aria's `DialogTrigger` on the system's `Popover` — the same white
+ * surface as a calendar or a small filter form — so placement, flipping when
+ * there is no room below, focus moving in and back to the `?`, and Escape are
+ * React Aria's, not a hand-written listener.
+ *
+ * The sentence also lives, hidden, next to the mark under `id`: a field points
+ * its `aria-describedby` there, and a closed popover is not in the page for a
+ * screen reader to read.
+ */
+export declare function Hint({ children, label, id, }: {
+    children: ReactNode;
+    /** Visible mark. The `?` is the default because it is the one that gets
+     *  recognized as «there is more to read». */
+    label?: ReactNode;
+    /** For `aria-describedby` on the field the help belongs to. */
+    id?: string;
+}): import("react").JSX.Element;

package/dist/primitives/hint/Hint.js

@@ -0,0 +1,42 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { tv } from "../../foundations/variants.js";
+import { Popover } from "../overlay/Popover.js";
+import { CircleHelp } from "lucide-react";
+import { useId } from "react";
+import { Button, Dialog, DialogTrigger } from "react-aria-components";
+const mark = tv({
+    base: "inline-flex size-4 shrink-0 cursor-help items-center justify-center rounded-pill text-muted outline-0 transition-colors duration-(--duration-instant) hover:bg-ink/8 hover:text-ink aria-expanded:bg-ink/8 aria-expanded:text-ink forced-colors:text-[ButtonText]",
+    variants: {
+        isFocusVisible: {
+            true: "outline-2 outline-offset-1 outline-primary forced-colors:outline-[Highlight]",
+        },
+    },
+});
+/**
+ * A sentence that does not fit on the page, attached to a mark.
+ *
+ * Context: `title` on a field is a native tooltip and nobody finds it. Odoo
+ * puts a `?` next to the label; pressing it is how you read the help without
+ * it eating a line. The mark is the affordance; the sentence is the content.
+ *
+ * ── Why a click and a popover, and not a `Tooltip` ──
+ *
+ * A `Tooltip` is a LABEL: a few words that show on hover and vanish when the
+ * pointer leaves — useless on a tablet, and gone before a sentence is read.
+ * This is content, so it opens on press (mouse, touch, Enter or Space) and
+ * stays until it is put away: a second press, Escape, or a click outside. It
+ * is React Aria's `DialogTrigger` on the system's `Popover` — the same white
+ * surface as a calendar or a small filter form — so placement, flipping when
+ * there is no room below, focus moving in and back to the `?`, and Escape are
+ * React Aria's, not a hand-written listener.
+ *
+ * The sentence also lives, hidden, next to the mark under `id`: a field points
+ * its `aria-describedby` there, and a closed popover is not in the page for a
+ * screen reader to read.
+ */
+export function Hint({ children, label = "?", id, }) {
+    const auto = useId();
+    const textId = id ?? auto;
+    return (_jsxs("span", { className: "inline-flex shrink-0", children: [_jsxs(DialogTrigger, { children: [_jsx(Button, { "aria-label": typeof children === "string" ? children : undefined, className: (state) => mark(state), children: label === "?" ? (_jsx(CircleHelp, { className: "size-3.5", strokeWidth: 2, "aria-hidden": true })) : (label) }), _jsx(Popover, { placement: "bottom", className: "max-w-64 rounded-box", children: _jsx(Dialog, { "aria-labelledby": textId, className: "px-3 py-2.5 text-micro leading-relaxed text-ink outline-0", children: children }) })] }), _jsx("span", { id: textId, hidden: true, children: children })] }));
+}

package/dist/primitives/hint/index.d.ts

@@ -0,0 +1 @@
+export { Hint } from "./Hint.js";

package/dist/primitives/hint/index.js

@@ -0,0 +1 @@
+export { Hint } from "./Hint.js";

package/dist/primitives/index.d.ts

@@ -0,0 +1,19 @@
+export * from "./block/index.js";
+export * from "./button/index.js";
+export * from "./cell/index.js";
+export * from "./choice/index.js";
+export * from "./date/index.js";
+export * from "./dialog/index.js";
+export * from "./disclosure/index.js";
+export * from "./field/index.js";
+export * from "./hint/index.js";
+export * from "./menu/index.js";
+export * from "./notice/index.js";
+export * from "./overlay/index.js";
+export * from "./picker/index.js";
+export * from "./surface/index.js";
+export * from "./table/index.js";
+export * from "./tabs/index.js";
+export * from "./tag/index.js";
+export * from "./toolbar/index.js";
+export * from "./value/index.js";

package/dist/primitives/index.js

@@ -0,0 +1,20 @@
+/* PRIMITIVES — a piece that does not know which screen it is on. */
+export * from "./block/index.js";
+export * from "./button/index.js";
+export * from "./cell/index.js";
+export * from "./choice/index.js";
+export * from "./date/index.js";
+export * from "./dialog/index.js";
+export * from "./disclosure/index.js";
+export * from "./field/index.js";
+export * from "./hint/index.js";
+export * from "./menu/index.js";
+export * from "./notice/index.js";
+export * from "./overlay/index.js";
+export * from "./picker/index.js";
+export * from "./surface/index.js";
+export * from "./table/index.js";
+export * from "./tabs/index.js";
+export * from "./tag/index.js";
+export * from "./toolbar/index.js";
+export * from "./value/index.js";

package/dist/primitives/menu/Menu.d.ts

@@ -0,0 +1,100 @@
+import { type ButtonRole, type ButtonSize } from "../button/Button.js";
+import type { LucideIcon } from "lucide-react";
+import type { ReactNode } from "react";
+export interface MenuOption {
+    id: string;
+    label: string;
+    /** The line below. It exists because a thirty-entry menu without hints forces
+     *  you to open each one to discover what it does. */
+    hint?: string;
+    icon?: LucideIcon;
+    /** For the menus that CHOOSE (group by, favorites) instead of executing. */
+    checked?: boolean;
+    /** A hairline ABOVE this option. It separates the three rows of a date —months,
+     *  quarters, years— which are one group because they combine, but read as
+     *  three because they answer at three different zooms. */
+    divider?: boolean;
+    /** Cómo se SACA esta opción cuando se dibuja como ficha, si sacarla no es lo mismo que
+     *  volver a elegirla. El filtro a medida es el caso: elegirlo abre el constructor, y eso
+     *  no es lo que tiene que pasar al tocar su ×. */
+    onRemove?: () => void;
+    disabled?: boolean;
+    /** Visual mark at the end of the label. A string is drawn as a pill
+     *  —"maqueta", "nuevo"—; anything else is drawn as is, which is how a status
+     *  `Tag` or an already formatted counter comes in. */
+    badge?: ReactNode;
+    /** What THIS option does. It exists on top of the menu's `onSelect` because a
+     *  menu built from a registry —twenty-five operations, each one with its own
+     *  action— has no reasonable `switch` on the other side. */
+    onSelect?: () => void;
+}
+export interface MenuGroup {
+    /** The group's label, in the brand voice. Without a label, the group is just
+     *  a separator — which also serves a purpose. */
+    label?: string;
+    /**
+     * The group folds under its label, and starts folded unless something in it
+     * is ticked.
+     *
+     * It exists for the DATE narrowings. «Fecha de pedido» is not one option, it
+     * is eleven —three months, four quarters, three years— and eleven options
+     * always open push the rest of the panel off the screen. A date is the only
+     * field that brings its own little calendar, so it is the only one that
+     * folds; the others are a list and a list does not need a door.
+     */
+    collapsible?: boolean;
+    options: MenuOption[];
+}
+declare const WIDTH: {
+    /** A menu of short verbs hanging off an icon: "duplicate", "delete". */
+    readonly sm: "min-w-44 max-w-64";
+    readonly md: "min-w-56 max-w-80";
+    readonly lg: "min-w-80 max-w-(--container-short)";
+};
+export declare function Menu({ label, groups, onSelect, surface, align, icon: Trigger, 
+/** The menu as a control of a list ("filters ▾") carries the chevron; the
+ *  actions `⋯` does not, because the icon already says there is more. */
+chevron, active, iconOnly, variant, searchPlaceholder, emptyText, width, role, size, title, closeOnSelect, }: {
+    label: string;
+    groups: readonly MenuGroup[];
+    onSelect?: (id: string) => void;
+    surface?: "canvas" | "chrome";
+    align?: "start" | "end";
+    icon?: LucideIcon;
+    chevron?: boolean;
+    /** Something is chosen inside. A filter menu that doesn't look different when
+     *  it filters is how someone ends up looking at a trimmed list without
+     *  knowing it. */
+    active?: boolean;
+    /** `text` removes the frame and the background: it is the menu of an
+     *  application BAR. `button` —the default— is the menu of a control. */
+    variant?: "button" | "text";
+    /** With a search box, the menu filters over label and hint. It only goes in
+     *  when there are enough entries for searching to gain something — a search
+     *  box on top of four options is one more control between the hand and what
+     *  was already visible. */
+    searchPlaceholder?: string;
+    emptyText?: string;
+    /** `md` for a menu of verbs; `lg` when the entries carry a hint that cannot be
+     *  truncated without losing its reason to exist. */
+    width?: keyof typeof WIDTH;
+    /** The trigger looks like a BUTTON of that role. It is for the menu that
+     *  starts something —"＋ Create"—, which has to look like the main action and
+     *  not like a control of the list. Without this, the trigger is the usual
+     *  small one. */
+    role?: ButtonRole;
+    size?: ButtonSize;
+    /** What explains the menu on hover. It is not drawn. */
+    title?: string;
+    /** Icon only. `label` becomes the accessible name and the `title`, and stops
+     *  being drawn — it is the actions `⋯`, where the icon already says there is
+     *  more.
+     *
+     *  The label does NOT become optional when hidden: a menu without an
+     *  accessible name is a menu a screen reader announces as "button". */
+    iconOnly?: boolean;
+    /** Column and filter menus toggle several options in a row. Closing after
+     *  each click turns three hides into three open-close round trips. */
+    closeOnSelect?: boolean;
+}): import("react").JSX.Element;
+export {};