react-fit-list 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marin Heđeš
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,259 @@
+# react-fit-list
+
+![Resizable FitList demo](./docs/demo.gif)
+
+`react-fit-list` is a small headless React utility for rendering a **single-line list that never wraps**.
+When the available width is too small, the list collapses extra items into an overflow affordance such as `+3`.
+
+It ships with:
+
+- a ready-to-use `<FitList />` component
+- a headless `useFitList()` hook for custom renderers
+- TypeScript types for component and hook APIs
+
+## Use cases
+
+`react-fit-list` works well for interfaces where wrapping would break the layout, such as:
+
+- tag and chip rows
+- recipient lists
+- breadcrumbs / metadata rows
+- inline filters
+- compact table or card cells
+
+## Installation
+
+```bash
+npm install react-fit-list
+```
+
+## Quick start
+
+```tsx
+import { FitList } from 'react-fit-list'
+
+const items = [
+  { id: 1, label: 'Security' },
+  { id: 2, label: 'Startups' },
+  { id: 3, label: 'Fintech' },
+  { id: 4, label: 'B2B SaaS' },
+]
+
+export function Example() {
+  return (
+    <div style={{ width: 240 }}>
+      <FitList
+        items={items}
+        getKey={(item) => item.id}
+        renderItem={(item) => (
+          <span
+            style={{
+              display: 'inline-flex',
+              alignItems: 'center',
+              border: '1px solid #d0d7de',
+              borderRadius: 999,
+              padding: '4px 10px',
+              fontSize: 12,
+              whiteSpace: 'nowrap',
+            }}
+          >
+            {item.label}
+          </span>
+        )}
+      />
+    </div>
+  )
+}
+```
+
+## How it works
+
+The package measures the container width and item widths, then determines how many items can fit in a single row.
+If not all items fit, the remainder is collapsed into an overflow element.
+
+By default:
+
+- the component keeps items on one row
+- overflow collapses from the end
+- the overflow trigger renders as `+N`
+- item widths are measured from the DOM in `live` mode
+
+## Component API
+
+### `<FitList />`
+
+```tsx
+import { FitList } from 'react-fit-list'
+```
+
+#### Required props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `items` | `readonly T[]` | Items to render. |
+| `getKey` | `(item: T, index: number) => React.Key` | Returns a stable key for each item. |
+| `renderItem` | `(item: T, index: number) => React.ReactNode` | Renders one item. |
+
+#### Optional props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `renderOverflow` | `(args) => React.ReactNode` | renders `+N` | Custom overflow renderer. Receives `{ hiddenCount, hiddenItems, visibleItems, isExpanded, setExpanded, toggle }`. |
+| `className` | `string` | — | Class for the root container. |
+| `listClassName` | `string` | — | Class for the visible-items wrapper. |
+| `itemClassName` | `string` | — | Class for each item wrapper. |
+| `overflowClassName` | `string` | — | Class for the overflow trigger wrapper. |
+| `measureClassName` | `string` | — | Class for hidden measurement nodes. Use when sizing depends on CSS classes. |
+| `emptyFallback` | `React.ReactNode` | `null` | Rendered when `items` is empty. |
+| `gap` | `number` | `8` | Pixel gap between items. |
+| `collapseFrom` | `'end' \| 'start'` | `'end'` | Collapse from the end or start of the list. |
+| `reserveOverflowSpace` | `boolean` | `false` | Reserve room for the overflow element even when everything currently fits. |
+| `overflowWidth` | `number` | auto | Fixed overflow width in pixels. Useful when the trigger width is known. |
+| `estimatedItemWidth` | `number \| ((item, index) => number)` | fallback `96` | Used in `estimate` mode or before live measurements are available. |
+| `measurementMode` | `'live' \| 'estimate'` | `'live'` | `live` measures DOM nodes, `estimate` uses `estimatedItemWidth`. |
+| `expanded` | `boolean` | uncontrolled | Controlled expanded state. |
+| `defaultExpanded` | `boolean` | `false` | Initial expanded state for uncontrolled usage. |
+| `onExpandedChange` | `(expanded: boolean) => void` | — | Called when expanded state changes. |
+| `as` | `keyof React.JSX.IntrinsicElements` | `'div'` | Root element tag name. |
+| `overflowAs` | `keyof React.JSX.IntrinsicElements` | `'button'` | Overflow element tag name. |
+
+## Hook API
+
+### `useFitList()`
+
+Use the hook when you want to own the markup but reuse the fitting logic.
+
+```tsx
+import { useFitList } from 'react-fit-list'
+```
+
+#### Hook options
+
+The hook accepts the same fitting-related options used by the component:
+
+- `items`
+- `getKey`
+- `reserveOverflowSpace`
+- `overflowWidth`
+- `gap`
+- `collapseFrom`
+- `estimatedItemWidth`
+- `measurementMode`
+- `expanded`
+- `defaultExpanded`
+- `onExpandedChange`
+- `measureOverflowWidth`
+
+#### Return value
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `containerRef` | `RefObject<HTMLDivElement \| null>` | Attach to the outer container whose width should be measured. |
+| `registerItem(key)` | `(node) => void` | Attach to each visible item wrapper. |
+| `registerMeasureItem(key)` | `(node) => void` | Attach to hidden measurement nodes for accurate width calculation. |
+| `registerOverflow(node)` | `(node) => void` | Attach to the overflow element. |
+| `visibleItems` | `T[]` | Items currently visible. |
+| `hiddenItems` | `T[]` | Items currently hidden. |
+| `hiddenCount` | `number` | Count of hidden items. |
+| `isExpanded` | `boolean` | Whether the list is expanded. |
+| `setExpanded` | `(expanded: boolean) => void` | Manually set expanded state. |
+| `toggleExpanded` | `() => void` | Toggle expanded state. |
+| `recompute` | `() => void` | Force a recalculation. |
+
+## Examples
+
+### Custom overflow label
+
+```tsx
+<FitList
+  items={items}
+  getKey={(item) => item.id}
+  renderItem={(item) => <Tag>{item.label}</Tag>}
+  renderOverflow={({ hiddenCount }) => (
+    <button type="button">+{hiddenCount}</button>
+  )}
+/>
+```
+
+### Collapse from the start
+
+Useful when the most recent or most important items are at the end.
+
+```tsx
+<FitList
+  items={items}
+  getKey={(item) => item.id}
+  renderItem={(item) => <Tag>{item.label}</Tag>}
+  collapseFrom="start"
+/>
+```
+
+### Estimate mode
+
+Estimate mode avoids relying on live measurement for every item and can be useful when item widths are predictable.
+
+```tsx
+<FitList
+  items={items}
+  getKey={(item) => item.id}
+  renderItem={(item) => <Tag>{item.label}</Tag>}
+  measurementMode="estimate"
+  estimatedItemWidth={(item) => Math.max(72, item.label.length * 8)}
+/>
+```
+
+### Controlled expanded state
+
+`FitList` does not impose any default click behavior for the overflow trigger. Use `renderOverflow` to define interactions such as opening a popover, modal, or expanding the list.
+
+Use `expanded` / `onExpandedChange` only when you intentionally want to control expansion behavior.
+
+```tsx
+function ControlledExample() {
+  const [expanded, setExpanded] = useState(false)
+
+  return (
+    <FitList
+      items={items}
+      getKey={(item) => item.id}
+      renderItem={(item) => <Tag>{item.label}</Tag>}
+      expanded={expanded}
+      onExpandedChange={setExpanded}
+    />
+  )
+}
+```
+
+## Styling guidance
+
+The package is intentionally headless. You control the appearance of the item contents.
+
+For best results:
+
+- keep each rendered item visually compact
+- ensure item content does not wrap internally (`white-space: nowrap` is usually correct)
+- use `measureClassName` when your measurement nodes need the same CSS as your visible nodes
+- provide `overflowWidth` when you know the trigger width and want more predictable calculations
+
+## Accessibility notes
+
+- By default the overflow trigger renders as a `<button>`.
+- When using a custom `renderOverflow`, make sure the resulting UI still communicates its action clearly.
+- If you switch `overflowAs` away from `button`, you are responsible for semantics and interaction behavior.
+
+## SSR / browser behavior
+
+- the package is safe to render during SSR
+- measurements are applied on the client
+- `ResizeObserver` is used when available
+- a `window.resize` listener is also attached as a fallback
+
+## Local development
+
+A Vite demo app is included in the `example/` directory. The demo uses a native resize handle instead of a slider so you can drag the container width directly.
+
+```bash
+cd example
+npm install
+npm run dev
+```

package/dist/index.cjs

@@ -0,0 +1,435 @@
+'use strict';
+
+var React = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
+var React__namespace = /*#__PURE__*/_interopNamespace(React);
+
+// src/components/FitList.tsx
+function useControllableState({
+  value,
+  defaultValue,
+  onChange
+}) {
+  const [internal, setInternal] = React.useState(defaultValue);
+  const isControlled = value !== void 0;
+  const current = isControlled ? value : internal;
+  const setValue = React.useCallback(
+    (next) => {
+      if (!isControlled) {
+        setInternal(next);
+      }
+      onChange?.(next);
+    },
+    [isControlled, onChange]
+  );
+  return [current, setValue];
+}
+
+// src/hooks/useFitList.tsx
+var useIsoLayoutEffect = typeof window !== "undefined" ? React.useLayoutEffect : React.useEffect;
+function getEstimatedWidth(item, index, estimatedItemWidth, fallback) {
+  if (typeof estimatedItemWidth === "function")
+    return estimatedItemWidth(item, index);
+  if (typeof estimatedItemWidth === "number") return estimatedItemWidth;
+  return fallback;
+}
+function useFitList({
+  items,
+  getKey,
+  reserveOverflowSpace = false,
+  overflowWidth,
+  gap = 8,
+  collapseFrom = "end",
+  estimatedItemWidth,
+  measurementMode = "live",
+  expanded,
+  defaultExpanded = false,
+  onExpandedChange,
+  measureOverflowWidth
+}) {
+  const containerRef = React.useRef(null);
+  const overflowRef = React.useRef(null);
+  const itemNodeMap = React.useRef(/* @__PURE__ */ new Map());
+  const measureNodeMap = React.useRef(/* @__PURE__ */ new Map());
+  const [visibleCount, setVisibleCount] = React.useState(items.length);
+  const [isExpanded, setExpanded] = useControllableState({
+    value: expanded,
+    defaultValue: defaultExpanded,
+    onChange: onExpandedChange
+  });
+  const compute = React.useCallback(() => {
+    if (isExpanded) {
+      setVisibleCount(items.length);
+      return;
+    }
+    const container = containerRef.current;
+    if (!container) {
+      setVisibleCount(items.length);
+      return;
+    }
+    const containerWidth = container.clientWidth;
+    if (!containerWidth) {
+      setVisibleCount(items.length);
+      return;
+    }
+    const keys = items.map(getKey);
+    const itemWidths = items.map((item, index) => {
+      const key = keys[index];
+      const measureNode = measureNodeMap.current.get(key);
+      const liveNode = itemNodeMap.current.get(key);
+      if (measurementMode === "live") {
+        if (measureNode) return measureNode.offsetWidth;
+        if (liveNode) return liveNode.offsetWidth;
+      }
+      return getEstimatedWidth(item, index, estimatedItemWidth, 96);
+    });
+    let nextVisible = items.length;
+    for (let count = items.length; count >= 0; count -= 1) {
+      const hiddenCount = items.length - count;
+      const visibleWidths = collapseFrom === "end" ? itemWidths.slice(0, count) : itemWidths.slice(items.length - count);
+      const itemsWidth = visibleWidths.reduce((sum, width) => sum + width, 0);
+      const itemsGap = count > 1 ? gap * (count - 1) : 0;
+      let currentOverflowWidth = 0;
+      if (hiddenCount > 0) {
+        if (typeof overflowWidth === "number") {
+          currentOverflowWidth = overflowWidth;
+        } else if (measureOverflowWidth) {
+          currentOverflowWidth = measureOverflowWidth(hiddenCount);
+        } else {
+          currentOverflowWidth = overflowRef.current?.offsetWidth ?? 44;
+        }
+      } else if (reserveOverflowSpace) {
+        if (typeof overflowWidth === "number") {
+          currentOverflowWidth = overflowWidth;
+        } else {
+          currentOverflowWidth = overflowRef.current?.offsetWidth ?? 44;
+        }
+      }
+      const overflowGap = (hiddenCount > 0 || reserveOverflowSpace) && count > 0 ? gap : 0;
+      const total = itemsWidth + itemsGap + overflowGap + currentOverflowWidth;
+      if (total <= containerWidth) {
+        nextVisible = count;
+        break;
+      }
+    }
+    setVisibleCount((prev) => prev === nextVisible ? prev : nextVisible);
+  }, [
+    collapseFrom,
+    estimatedItemWidth,
+    gap,
+    getKey,
+    isExpanded,
+    items,
+    measurementMode,
+    measureOverflowWidth,
+    overflowWidth,
+    reserveOverflowSpace
+  ]);
+  useIsoLayoutEffect(() => {
+    compute();
+  }, [compute]);
+  useIsoLayoutEffect(() => {
+    const container = containerRef.current;
+    if (!container || typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver(() => {
+      requestAnimationFrame(compute);
+    });
+    observer.observe(container);
+    return () => observer.disconnect();
+  }, [compute]);
+  React.useEffect(() => {
+    if (typeof window === "undefined") return;
+    const onResize = () => compute();
+    window.addEventListener("resize", onResize);
+    return () => window.removeEventListener("resize", onResize);
+  }, [compute]);
+  const registerItem = React.useCallback(
+    (key) => (node) => {
+      if (node) {
+        itemNodeMap.current.set(key, node);
+      } else {
+        itemNodeMap.current.delete(key);
+      }
+    },
+    []
+  );
+  const registerMeasureItem = React.useCallback(
+    (key) => (node) => {
+      if (node) {
+        measureNodeMap.current.set(key, node);
+      } else {
+        measureNodeMap.current.delete(key);
+      }
+    },
+    []
+  );
+  const registerOverflow = React.useCallback((node) => {
+    overflowRef.current = node;
+  }, []);
+  const clampedVisibleCount = Math.max(0, Math.min(visibleCount, items.length));
+  const visibleItems = React.useMemo(() => {
+    if (isExpanded) return [...items];
+    if (collapseFrom === "end") return items.slice(0, clampedVisibleCount);
+    return items.slice(items.length - clampedVisibleCount);
+  }, [clampedVisibleCount, collapseFrom, isExpanded, items]);
+  const hiddenItems = React.useMemo(() => {
+    if (isExpanded) return [];
+    if (collapseFrom === "end") return items.slice(clampedVisibleCount);
+    return items.slice(0, items.length - clampedVisibleCount);
+  }, [clampedVisibleCount, collapseFrom, isExpanded, items]);
+  const toggleExpanded = React.useCallback(() => {
+    setExpanded(!isExpanded);
+  }, [isExpanded, setExpanded]);
+  return {
+    containerRef,
+    registerItem,
+    registerMeasureItem,
+    registerOverflow,
+    visibleItems,
+    hiddenItems,
+    hiddenCount: hiddenItems.length,
+    isExpanded,
+    setExpanded,
+    toggleExpanded,
+    recompute: compute
+  };
+}
+function defaultOverflow({ hiddenCount }) {
+  return /* @__PURE__ */ jsxRuntime.jsxs("span", { children: [
+    "+",
+    hiddenCount
+  ] });
+}
+function FitList({
+  items,
+  getKey,
+  renderItem,
+  renderOverflow = defaultOverflow,
+  className,
+  listClassName,
+  itemClassName,
+  overflowClassName,
+  measureClassName,
+  emptyFallback = null,
+  gap = 8,
+  collapseFrom = "end",
+  reserveOverflowSpace = false,
+  overflowWidth,
+  estimatedItemWidth,
+  measurementMode = "live",
+  expanded,
+  defaultExpanded = false,
+  onExpandedChange,
+  as = "div",
+  onOverflowClick,
+  overflowAs = "button"
+}) {
+  const Component = as;
+  const OverflowComponent = overflowAs;
+  const overflowMeasureRef = React__namespace.useRef(null);
+  const isDefaultOverflowRenderer = renderOverflow === defaultOverflow;
+  const measureOverflowWidth = React__namespace.useCallback(
+    (hiddenCount2) => {
+      if (typeof overflowWidth === "number") return overflowWidth;
+      const node = overflowMeasureRef.current;
+      if (!node) return 44;
+      if (isDefaultOverflowRenderer) {
+        const previous = node.textContent;
+        node.textContent = `+${hiddenCount2}`;
+        const width = node.offsetWidth;
+        node.textContent = previous;
+        return width;
+      }
+      return node.offsetWidth;
+    },
+    [isDefaultOverflowRenderer, overflowWidth]
+  );
+  const {
+    containerRef,
+    registerItem,
+    registerMeasureItem,
+    registerOverflow,
+    visibleItems,
+    hiddenItems,
+    hiddenCount,
+    isExpanded,
+    setExpanded,
+    toggleExpanded
+  } = useFitList({
+    items,
+    getKey,
+    gap,
+    collapseFrom,
+    reserveOverflowSpace,
+    overflowWidth,
+    estimatedItemWidth,
+    measurementMode,
+    expanded,
+    defaultExpanded,
+    onExpandedChange,
+    measureOverflowWidth
+  });
+  const visibleEntries = React__namespace.useMemo(() => {
+    if (isExpanded) {
+      return items.map((item, index) => ({ item, index }));
+    }
+    if (collapseFrom === "end") {
+      return items.slice(0, visibleItems.length).map((item, index) => ({ item, index }));
+    }
+    const startIndex = items.length - visibleItems.length;
+    return items.slice(startIndex).map((item, index) => ({ item, index: startIndex + index }));
+  }, [collapseFrom, isExpanded, items, visibleItems.length]);
+  if (items.length === 0) {
+    return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: emptyFallback });
+  }
+  const overflowArgs = {
+    hiddenCount,
+    hiddenItems: [...hiddenItems],
+    visibleItems: [...visibleItems],
+    isExpanded,
+    setExpanded,
+    toggle: toggleExpanded
+  };
+  const overflowChildren = renderOverflow(overflowArgs);
+  const overflowButtonProps = {
+    className: overflowClassName,
+    type: "button",
+    onClick: (event) => onOverflowClick?.(overflowArgs, event),
+    "aria-expanded": isExpanded,
+    children: overflowChildren
+  };
+  const content = /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+    /* @__PURE__ */ jsxRuntime.jsx(
+      "div",
+      {
+        className: listClassName,
+        style: {
+          display: "flex",
+          alignItems: "center",
+          gap,
+          minWidth: 0,
+          flex: "1 1 auto",
+          overflow: "hidden"
+        },
+        children: visibleEntries.map(({ item, index }) => {
+          const key = getKey(item, index);
+          return /* @__PURE__ */ jsxRuntime.jsx(
+            "div",
+            {
+              ref: registerItem(key),
+              className: itemClassName,
+              style: {
+                minWidth: 0,
+                flex: "0 0 auto",
+                whiteSpace: "nowrap"
+              },
+              children: renderItem(item, index)
+            },
+            key
+          );
+        })
+      }
+    ),
+    (hiddenCount > 0 || reserveOverflowSpace) && /* @__PURE__ */ jsxRuntime.jsx(
+      "div",
+      {
+        ref: registerOverflow,
+        style: {
+          visibility: hiddenCount > 0 ? "visible" : "hidden",
+          flex: "0 0 auto",
+          whiteSpace: "nowrap",
+          display: "block"
+        },
+        children: hiddenCount > 0 ? overflowAs === "button" ? /* @__PURE__ */ jsxRuntime.jsx("button", { ...overflowButtonProps }) : React__namespace.createElement(
+          OverflowComponent,
+          { className: overflowClassName },
+          overflowChildren
+        ) : /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: "+0" })
+      }
+    )
+  ] });
+  const root = React__namespace.createElement(
+    Component,
+    {
+      ref: containerRef,
+      className,
+      style: {
+        display: "flex",
+        alignItems: "center",
+        gap,
+        minWidth: 0,
+        whiteSpace: "nowrap"
+      }
+    },
+    content
+  );
+  return /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+    root,
+    /* @__PURE__ */ jsxRuntime.jsx(
+      "div",
+      {
+        "aria-hidden": "true",
+        style: {
+          pointerEvents: "none",
+          position: "fixed",
+          top: 0,
+          left: 0,
+          zIndex: -1,
+          overflow: "hidden",
+          opacity: 0
+        },
+        children: /* @__PURE__ */ jsxRuntime.jsxs("div", { style: { display: "flex", alignItems: "center", gap }, children: [
+          items.map((item, index) => {
+            const key = getKey(item, index);
+            return /* @__PURE__ */ jsxRuntime.jsx(
+              "span",
+              {
+                ref: registerMeasureItem(key),
+                className: measureClassName ?? itemClassName,
+                style: {
+                  display: "inline-flex",
+                  whiteSpace: "nowrap"
+                },
+                children: renderItem(item, index)
+              },
+              `measure:${String(key)}`
+            );
+          }),
+          /* @__PURE__ */ jsxRuntime.jsx(
+            "span",
+            {
+              ref: overflowMeasureRef,
+              className: overflowClassName,
+              style: { display: "inline-flex", whiteSpace: "nowrap" },
+              children: overflowChildren
+            }
+          )
+        ] })
+      }
+    )
+  ] });
+}
+
+exports.FitList = FitList;
+exports.useFitList = useFitList;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map