@hoardodile/ui 0.1.2 → 0.1.4

package/dist/components/tag-chip.d.ts

@@ -0,0 +1,87 @@
+import * as React from 'react';
+import { ReactNode, ReactElement, MouseEvent, ComponentPropsWithoutRef } from 'react';
+
+/** The two sanctioned chip sizes: `sm` (default, `px-2 py-1`) for cards and
+    inline rows, `md` (`px-2 py-1.5`) for the filterer facets (Categories,
+    Traits, Relations). */
+type TagChipSize = "sm" | "md";
+type TagChipBaseProps = {
+    /**
+     * Effective display color. Special names (`silver`, `gold`, `rainbow`,
+     * ...) render their SVG texture; an empty string falls back to the
+     * default muted chip, taking the primary fill when `active`. Ignored
+     * when `border` is set — bordered modes never take a tint.
+     */
+    readonly color?: string;
+    /** Chip height tier — see {@link TagChipSize}. */
+    readonly size?: TagChipSize;
+    /**
+     * Border mode instead of the fill/ghost anatomies. Only `"dashed"`
+     * exists today (add pills, unused entities): a `border-dashed` hairline
+     * with muted ink and no color tint — `active` swaps in the accent fill
+     * with a transparent border so the width never moves with the state.
+     */
+    readonly border?: "dashed";
+    /** Selected: colored chips deepen to their hover tint, special styles
+        switch to their own active appearance, uncolored chips take the
+        primary fill. */
+    readonly active?: boolean;
+    /** Leading icon; rides the chip's own gap, so no wrapper is needed. */
+    readonly icon?: ReactNode;
+    /** False removes the right border-radius so the chip can glue flush
+        against a sibling (e.g. the category rail's chevron). */
+    readonly roundedRight?: boolean;
+    /**
+     * Root element mode: `"inline"` (default) renders a plain `<span>`,
+     * `"button"` a real `<button type="button">`. The element is chosen
+     * only from this prop (or `render`) — passing an `onClick` never
+     * changes the element, so interactive wrappers (hover cards,
+     * popovers) that merge click handlers onto the chip cannot swap its
+     * DOM node mid-interaction.
+     */
+    readonly display?: "inline" | "button";
+    /**
+     * Polymorphic root: pass a `render={<button ... />}` element to render
+     * the chip as that element. The chip's own classes, style, handlers,
+     * texture and icon merge onto it, and the chip's children become the
+     * element's children — so the render element should carry only its own
+     * props. Wins over `display`; `display="button"` is the plain way to
+     * get a real button without supplying a render element.
+     */
+    readonly render?: ReactElement<Record<string, unknown>>;
+    /**
+     * Trailing suffix, separated from the label by a middle dot (e.g. a
+     * trait's kind "cm" or a count). Rendered at the label's own size —
+     * same line box, so the chip height never depends on the suffix —
+     * with muted ink and a bold dot.
+     */
+    readonly suffix?: ReactNode;
+    readonly children?: ReactNode;
+    readonly onMouseDown?: (event: MouseEvent<HTMLSpanElement>) => void;
+};
+type TagChipProps = TagChipBaseProps & Omit<ComponentPropsWithoutRef<"button">, keyof TagChipBaseProps>;
+/**
+ * The one tag chip: a single rounded pill (inline-flex, `rounded-sm`,
+ * `px-2 py-1`, 12px text) that may carry an icon and a special SVG
+ * texture. It renders as a span by default; interactive surfaces pass
+ * `display="button"` (or `render={<button ... />}` for a custom root,
+ * e.g. a navigation anchor) and the chip's styling lands on that
+ * element — one element in the DOM plus a single text wrapper, no
+ * deeper nesting.
+ *
+ * The root element is decided purely by `display`/`render` — never by
+ * the presence of an `onClick`, so a chip's DOM element cannot change
+ * between renders (the hover-card trigger merge in {@link TagChipHover}
+ * relies on this).
+ *
+ * Coloring is delegated to {@link resolveTagChipSurface} so cards,
+ * pickers, the doc editor and the character pills all share one
+ * definition of "what a colored tag looks like".
+ *
+ * The chip forwards its root ref so composition wrappers (e.g. the
+ * {@link TagChipHover} preview-card trigger, which clones the chip and
+ * attaches a DOM ref for anchoring) can reach the actual element.
+ */
+declare const TagChip: React.ForwardRefExoticComponent<TagChipBaseProps & Omit<Omit<React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref">, keyof TagChipBaseProps> & React.RefAttributes<HTMLElement>>;
+
+export { TagChip, type TagChipProps, type TagChipSize };