@edux-design/chips 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# @edux-design/chips
+
+## 0.3.0
+
+### Minor Changes
+
+- Add ActionChip as a distinct native button with native ref and activation, count and adornment content, and visual selected state. Preserve the existing div-based Chip and removal contract; do not introduce nested interactive controls.
+
+## 0.2.0
+
+### Minor Changes
+
+- Add typed removeButtonProps for native remove-button descriptions, refs and composed handlers while preserving Chip removal, label and disabled semantics. Keep collection state and post-removal focus with the host.
+
+## 0.1.0
+
+### Minor Changes
+
+- Moved react / dom to peer deps
+
+### Patch Changes
+
+- Updated dependencies
+  - @edux-design/icons@0.1.0
+  - @edux-design/utils@0.1.0

package/README.md

@@ -1,6 +1,6 @@
 # @edux-design/chips
 
-Token-driven filter chips that compose existing primitives (like `TagNumber`) without extra props. Each chip renders a pill with a count, label, and optional dismiss control that mirrors the spec in `chips.png`.
+Token-driven compact chips. `Chip` renders an informational or removable div-root pill; `ActionChip` renders a native button for filter actions and overlay triggers. Both support label/count composition with existing primitives.
 
 ---
 
@@ -14,6 +14,18 @@ npm install @edux-design/chips @edux-design/utils @edux-design/icons
 
 The package ships React components and depends on `react@^19.1.0` / `react-dom@^19.1.0`.
 
+## Token contract
+
+Small chips use the shared `min-h-32` token and both chip sizes use the shared
+`size-16` token for the remove control. The default chip remains `40px` tall
+through an explicit component-owned `min-h-[40px]` value because the current
+theme has no 40px spacing or control token; introducing a new semantic token
+would be broader than this package change and is intentionally deferred.
+
+Padding, gaps, borders, colours, and focus treatment use existing Edux numeric
+and semantic tokens. Consumers should import `@edux-design/tokens/theme` so
+those utilities resolve consistently.
+
 ---
 
 ## Usage
@@ -25,7 +37,9 @@ import { TagNumber } from "@edux-design/tags";
 export function Filters({ onRemove }) {
   return (
     <Chip label="Label" onRemove={onRemove}>
-      <TagNumber variant="brand" tone="solid">999</TagNumber>
+      <TagNumber variant="brand" tone="solid">
+        999
+      </TagNumber>
     </Chip>
   );
 }
@@ -33,13 +47,13 @@ export function Filters({ onRemove }) {
 
 ### Key Props
 
-| Prop | Description |
-| ---- | ----------- |
-| `label` | Primary text rendered inside the chip (truncated when needed). |
-| `size` | `"default"` (40px tall) or `"small"` (32px tall). |
-| `onRemove` | When provided, renders a close icon button that calls the handler. |
-| `removeLabel` | Accessible label for the close button. Defaults to `"Remove chip"`. |
-| `disabled` | Mutes colors, disables the close button, and removes pointer interactions. |
+| Prop          | Description                                                                |
+| ------------- | -------------------------------------------------------------------------- |
+| `label`       | Primary text rendered inside the chip (truncated when needed).             |
+| `size`        | `"default"` (40px tall) or `"small"` (32px tall).                          |
+| `onRemove`    | When provided, renders a close icon button that calls the handler.         |
+| `removeLabel` | Accessible label for the close button. Defaults to `"Remove chip"`.        |
+| `disabled`    | Mutes colors, disables the close button, and removes pointer interactions. |
 
 `children` are rendered before the label, so you can compose `TagNumber` (or any other primitive) directly inside the chip without a dedicated prop.
 
@@ -62,3 +76,33 @@ Stories live under `src/demos/Chip.stories.jsx` with size + state examples pulle
 - Focus, hover, pressed, dragged, and inactive visuals are all handled via Tailwind utility classes wired to the shared design tokens.
 - The chip container uses `focus-within` so the focus ring appears when the remove button is tabbed to.
 - Feel free to slot other components ahead of the label; the layout simply spaces whatever you supply, so TagNumber composition stays entirely declarative.
+
+## Native action/filter trigger
+
+```jsx
+import { ActionChip } from "@edux-design/chips";
+import { TagNumber } from "@edux-design/tags";
+import { Chevron } from "@edux-design/icons";
+
+<ActionChip
+  label="Stages"
+  selected={selectedStages.length > 0}
+  count={
+    selectedStages.length > 0 ? (
+      <TagNumber>{selectedStages.length}</TagNumber>
+    ) : null
+  }
+  endAdornment={<Chevron aria-hidden="true" />}
+  onClick={openStageFilter}
+/>;
+```
+
+ActionChip forwards native button props and an `HTMLButtonElement` ref, defaults
+to `type="button"`, and composes with Menu/Popover triggers. `selected` is visual
+filter state; popup expansion comes from `aria-expanded` or `data-state="open"`.
+Set native `aria-pressed` only for actual toggle actions. Labels and slots must
+contain noninteractive content; removal remains on the div-root Chip.
+
+Its `default` and `small` minimum heights retain existing 40px/32px chip geometry.
+See [ActionChip contract and examples](./docs/action-chip.md) and the
+[read-only host inventory](./docs/action-chip-inventory.md).

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import * as react from 'react';
+import React from 'react';
 
 /**
  * Token-driven chip that composes existing primitives (i.e. TagNumber) inside.
@@ -9,8 +9,40 @@ import * as react from 'react';
  *   onRemove?: (event: React.MouseEvent<HTMLButtonElement>) => void,
  *   removeLabel?: string,
  *   disabled?: boolean,
+ *   removeButtonProps?: Omit<React.ComponentPropsWithRef<"button">, "type"|"disabled"|"aria-label"|"aria-labelledby"|"children">,
  * }} ChipProps
  */
-declare const Chip: react.ForwardRefExoticComponent<react.RefAttributes<any>>;
+/** @type {React.ForwardRefExoticComponent<ChipProps & React.RefAttributes<HTMLDivElement>>} */
+declare const Chip: React.ForwardRefExoticComponent<ChipProps & React.RefAttributes<HTMLDivElement>>;
+/**
+ * Token-driven chip that composes existing primitives (i.e. TagNumber) inside.
+ */
+type ChipProps = React.HTMLAttributes<HTMLDivElement> & {
+    label?: React.ReactNode;
+    size?: "default" | "small";
+    onRemove?: (event: React.MouseEvent<HTMLButtonElement>) => void;
+    removeLabel?: string;
+    disabled?: boolean;
+    removeButtonProps?: Omit<React.ComponentPropsWithRef<"button">, "type" | "disabled" | "aria-label" | "aria-labelledby" | "children">;
+};
+
+interface ActionChipProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Visible label; children are used when label is undefined. Supply noninteractive content. */
+    label?: React.ReactNode;
+    /** Chip-specific geometry, matching Chip's existing 40px/32px minimum heights. */
+    size?: "default" | "small";
+    /** Visual filter state only. Does not imply aria-pressed or popup expansion. */
+    selected?: boolean;
+    /** Noninteractive count content before the label. The host owns its visibility and value. */
+    count?: React.ReactNode;
+    startAdornment?: React.ReactNode;
+    endAdornment?: React.ReactNode;
+    /** Use the separate div-root Chip for removal. */
+    onRemove?: never;
+    removeLabel?: never;
+    removeButtonProps?: never;
+}
+/** Native action/overlay trigger. The host owns filter state and popup behaviour. */
+declare const ActionChip: React.ForwardRefExoticComponent<ActionChipProps & React.RefAttributes<HTMLButtonElement>>;
 
-export { Chip };
+export { ActionChip, Chip };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import * as react from 'react';
+import React from 'react';
 
 /**
  * Token-driven chip that composes existing primitives (i.e. TagNumber) inside.
@@ -9,8 +9,40 @@ import * as react from 'react';
  *   onRemove?: (event: React.MouseEvent<HTMLButtonElement>) => void,
  *   removeLabel?: string,
  *   disabled?: boolean,
+ *   removeButtonProps?: Omit<React.ComponentPropsWithRef<"button">, "type"|"disabled"|"aria-label"|"aria-labelledby"|"children">,
  * }} ChipProps
  */
-declare const Chip: react.ForwardRefExoticComponent<react.RefAttributes<any>>;
+/** @type {React.ForwardRefExoticComponent<ChipProps & React.RefAttributes<HTMLDivElement>>} */
+declare const Chip: React.ForwardRefExoticComponent<ChipProps & React.RefAttributes<HTMLDivElement>>;
+/**
+ * Token-driven chip that composes existing primitives (i.e. TagNumber) inside.
+ */
+type ChipProps = React.HTMLAttributes<HTMLDivElement> & {
+    label?: React.ReactNode;
+    size?: "default" | "small";
+    onRemove?: (event: React.MouseEvent<HTMLButtonElement>) => void;
+    removeLabel?: string;
+    disabled?: boolean;
+    removeButtonProps?: Omit<React.ComponentPropsWithRef<"button">, "type" | "disabled" | "aria-label" | "aria-labelledby" | "children">;
+};
+
+interface ActionChipProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Visible label; children are used when label is undefined. Supply noninteractive content. */
+    label?: React.ReactNode;
+    /** Chip-specific geometry, matching Chip's existing 40px/32px minimum heights. */
+    size?: "default" | "small";
+    /** Visual filter state only. Does not imply aria-pressed or popup expansion. */
+    selected?: boolean;
+    /** Noninteractive count content before the label. The host owns its visibility and value. */
+    count?: React.ReactNode;
+    startAdornment?: React.ReactNode;
+    endAdornment?: React.ReactNode;
+    /** Use the separate div-root Chip for removal. */
+    onRemove?: never;
+    removeLabel?: never;
+    removeButtonProps?: never;
+}
+/** Native action/overlay trigger. The host owns filter state and popup behaviour. */
+declare const ActionChip: React.ForwardRefExoticComponent<ActionChipProps & React.RefAttributes<HTMLButtonElement>>;
 
-export { Chip };
+export { ActionChip, Chip };

package/dist/index.js

@@ -29,6 +29,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.js
 var index_exports = {};
 __export(index_exports, {
+  ActionChip: () => ActionChip,
   Chip: () => Chip
 });
 module.exports = __toCommonJS(index_exports);
@@ -41,11 +42,11 @@ var import_jsx_runtime = require("react/jsx-runtime");
 var SIZE_MAP = {
   default: {
     container: "text-sm min-h-[40px] px-8 py-6 gap-8",
-    close: "h-[16px] w-[16px]"
+    close: "size-16"
   },
   small: {
-    container: "text-xs min-h-[32px] px-8 py-4 gap-6",
-    close: "h-[16px] w-[16px]"
+    container: "text-xs min-h-32 px-8 py-4 gap-6",
+    close: "size-16"
   }
 };
 var BASE_STYLES = (0, import_utils.cx)(
@@ -64,9 +65,15 @@ var Chip = (0, import_react.forwardRef)(function Chip2({
   onRemove,
   removeLabel = "Remove chip",
   disabled = false,
+  removeButtonProps = {},
   className,
   ...rest
 }, ref) {
+  const {
+    className: removeClassName,
+    onClick: onRemoveClick,
+    ...buttonProps
+  } = removeButtonProps;
   const sizeStyles = SIZE_MAP[size] ?? SIZE_MAP.default;
   const containerClass = (0, import_utils.cx)(
     BASE_STYLES,
@@ -86,6 +93,7 @@ var Chip = (0, import_react.forwardRef)(function Chip2({
       className: containerClass,
       "data-disabled": disabled ? "true" : void 0,
       ...rest,
+      "aria-disabled": disabled ? true : rest["aria-disabled"],
       children: [
         /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("span", { className: "flex min-w-0 flex-1 items-center gap-6", children: [
           shouldRenderChildren && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: "flex items-center gap-4 shrink-0 [&>*]:shrink-0", children: normalizedChildren.map(
@@ -96,12 +104,16 @@ var Chip = (0, import_react.forwardRef)(function Chip2({
         onRemove && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
           "button",
           {
+            ...buttonProps,
             type: "button",
             disabled,
             "aria-label": removeLabel,
+            "aria-labelledby": void 0,
             onClick: (event) => {
               event.stopPropagation();
-              onRemove(event);
+              if (disabled) return;
+              onRemoveClick?.(event);
+              if (!event.defaultPrevented) onRemove(event);
             },
             className: (0, import_utils.cx)(
               "ml-4 inline-flex items-center justify-center rounded-full text-fg-subtle",
@@ -110,7 +122,8 @@ var Chip = (0, import_react.forwardRef)(function Chip2({
               "focus-visible:shadow-focus focus-visible:outline-none",
               "active:bg-bg-primary-subtle-90",
               disabled && "opacity-60 pointer-events-none bg-transparent text-fg-inactive",
-              sizeStyles.close
+              sizeStyles.close,
+              removeClassName
             ),
             children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_icons.Close, {})
           }
@@ -119,7 +132,69 @@ var Chip = (0, import_react.forwardRef)(function Chip2({
     }
   );
 });
+
+// src/elements/ActionChip.tsx
+var import_react2 = require("react");
+var import_utils2 = require("@edux-design/utils");
+var import_jsx_runtime2 = require("react/jsx-runtime");
+var hasSlot = (node) => node != null && typeof node !== "boolean";
+var sizes = {
+  default: "text-sm min-h-[40px] px-8 py-6 gap-8",
+  small: "text-xs min-h-32 px-8 py-4 gap-6"
+};
+var ActionChip = (0, import_react2.forwardRef)(
+  function ActionChip2({
+    label,
+    children,
+    size = "default",
+    selected = false,
+    count,
+    startAdornment,
+    endAdornment,
+    disabled = false,
+    type = "button",
+    className,
+    // Do not leak unsupported removal props onto the native button in JS hosts.
+    onRemove: _onRemove,
+    removeLabel: _removeLabel,
+    removeButtonProps: _removeButtonProps,
+    ...props
+  }, ref) {
+    const expanded = props["aria-expanded"] === true || props["aria-expanded"] === "true";
+    return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+      "button",
+      {
+        ...props,
+        ref,
+        type,
+        disabled,
+        "data-selected": selected ? "true" : void 0,
+        className: (0, import_utils2.cx)(
+          "inline-flex w-fit max-w-full min-w-0 items-center rounded-full border border-border-minimal bg-bg-base text-fg-base shadow-sm",
+          "transition-all duration-200 ease-out cursor-pointer",
+          "hover:border-border-primary-base hover:bg-bg-primary-subtle",
+          "active:border-border-primary-emphasis active:bg-bg-primary-subtle-90",
+          "focus-visible:shadow-focus focus-visible:border-border-emphasis focus-visible:outline-none",
+          "data-[state=open]:border-border-primary-base data-[state=open]:bg-bg-primary-subtle",
+          sizes[size],
+          (selected || expanded) && "border-border-primary-base bg-bg-primary-subtle",
+          disabled && "bg-bg-inactive text-fg-inactive border-border-subtle cursor-not-allowed pointer-events-none",
+          className
+        ),
+        children: /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("span", { className: "flex min-w-0 flex-1 items-center gap-6", children: [
+          hasSlot(startAdornment) && /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { className: "inline-flex shrink-0 items-center", children: startAdornment }),
+          hasSlot(count) && /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { className: "inline-flex shrink-0 items-center", children: count }),
+          /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("span", { className: "flex min-w-0 items-center gap-8", children: [
+            /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { className: "min-w-0 truncate text-left", children: label === void 0 ? children : label }),
+            hasSlot(endAdornment) && /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { className: "inline-flex shrink-0 items-center", children: endAdornment })
+          ] })
+        ] })
+      }
+    );
+  }
+);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ActionChip,
   Chip
 });

package/dist/index.mjs

@@ -6,11 +6,11 @@ import { jsx, jsxs } from "react/jsx-runtime";
 var SIZE_MAP = {
   default: {
     container: "text-sm min-h-[40px] px-8 py-6 gap-8",
-    close: "h-[16px] w-[16px]"
+    close: "size-16"
   },
   small: {
-    container: "text-xs min-h-[32px] px-8 py-4 gap-6",
-    close: "h-[16px] w-[16px]"
+    container: "text-xs min-h-32 px-8 py-4 gap-6",
+    close: "size-16"
   }
 };
 var BASE_STYLES = cx(
@@ -29,9 +29,15 @@ var Chip = forwardRef(function Chip2({
   onRemove,
   removeLabel = "Remove chip",
   disabled = false,
+  removeButtonProps = {},
   className,
   ...rest
 }, ref) {
+  const {
+    className: removeClassName,
+    onClick: onRemoveClick,
+    ...buttonProps
+  } = removeButtonProps;
   const sizeStyles = SIZE_MAP[size] ?? SIZE_MAP.default;
   const containerClass = cx(
     BASE_STYLES,
@@ -51,6 +57,7 @@ var Chip = forwardRef(function Chip2({
       className: containerClass,
       "data-disabled": disabled ? "true" : void 0,
       ...rest,
+      "aria-disabled": disabled ? true : rest["aria-disabled"],
       children: [
         /* @__PURE__ */ jsxs("span", { className: "flex min-w-0 flex-1 items-center gap-6", children: [
           shouldRenderChildren && /* @__PURE__ */ jsx("span", { className: "flex items-center gap-4 shrink-0 [&>*]:shrink-0", children: normalizedChildren.map(
@@ -61,12 +68,16 @@ var Chip = forwardRef(function Chip2({
         onRemove && /* @__PURE__ */ jsx(
           "button",
           {
+            ...buttonProps,
             type: "button",
             disabled,
             "aria-label": removeLabel,
+            "aria-labelledby": void 0,
             onClick: (event) => {
               event.stopPropagation();
-              onRemove(event);
+              if (disabled) return;
+              onRemoveClick?.(event);
+              if (!event.defaultPrevented) onRemove(event);
             },
             className: cx(
               "ml-4 inline-flex items-center justify-center rounded-full text-fg-subtle",
@@ -75,7 +86,8 @@ var Chip = forwardRef(function Chip2({
               "focus-visible:shadow-focus focus-visible:outline-none",
               "active:bg-bg-primary-subtle-90",
               disabled && "opacity-60 pointer-events-none bg-transparent text-fg-inactive",
-              sizeStyles.close
+              sizeStyles.close,
+              removeClassName
             ),
             children: /* @__PURE__ */ jsx(Close, {})
           }
@@ -84,6 +96,68 @@ var Chip = forwardRef(function Chip2({
     }
   );
 });
+
+// src/elements/ActionChip.tsx
+import { forwardRef as forwardRef2 } from "react";
+import { cx as cx2 } from "@edux-design/utils";
+import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
+var hasSlot = (node) => node != null && typeof node !== "boolean";
+var sizes = {
+  default: "text-sm min-h-[40px] px-8 py-6 gap-8",
+  small: "text-xs min-h-32 px-8 py-4 gap-6"
+};
+var ActionChip = forwardRef2(
+  function ActionChip2({
+    label,
+    children,
+    size = "default",
+    selected = false,
+    count,
+    startAdornment,
+    endAdornment,
+    disabled = false,
+    type = "button",
+    className,
+    // Do not leak unsupported removal props onto the native button in JS hosts.
+    onRemove: _onRemove,
+    removeLabel: _removeLabel,
+    removeButtonProps: _removeButtonProps,
+    ...props
+  }, ref) {
+    const expanded = props["aria-expanded"] === true || props["aria-expanded"] === "true";
+    return /* @__PURE__ */ jsx2(
+      "button",
+      {
+        ...props,
+        ref,
+        type,
+        disabled,
+        "data-selected": selected ? "true" : void 0,
+        className: cx2(
+          "inline-flex w-fit max-w-full min-w-0 items-center rounded-full border border-border-minimal bg-bg-base text-fg-base shadow-sm",
+          "transition-all duration-200 ease-out cursor-pointer",
+          "hover:border-border-primary-base hover:bg-bg-primary-subtle",
+          "active:border-border-primary-emphasis active:bg-bg-primary-subtle-90",
+          "focus-visible:shadow-focus focus-visible:border-border-emphasis focus-visible:outline-none",
+          "data-[state=open]:border-border-primary-base data-[state=open]:bg-bg-primary-subtle",
+          sizes[size],
+          (selected || expanded) && "border-border-primary-base bg-bg-primary-subtle",
+          disabled && "bg-bg-inactive text-fg-inactive border-border-subtle cursor-not-allowed pointer-events-none",
+          className
+        ),
+        children: /* @__PURE__ */ jsxs2("span", { className: "flex min-w-0 flex-1 items-center gap-6", children: [
+          hasSlot(startAdornment) && /* @__PURE__ */ jsx2("span", { className: "inline-flex shrink-0 items-center", children: startAdornment }),
+          hasSlot(count) && /* @__PURE__ */ jsx2("span", { className: "inline-flex shrink-0 items-center", children: count }),
+          /* @__PURE__ */ jsxs2("span", { className: "flex min-w-0 items-center gap-8", children: [
+            /* @__PURE__ */ jsx2("span", { className: "min-w-0 truncate text-left", children: label === void 0 ? children : label }),
+            hasSlot(endAdornment) && /* @__PURE__ */ jsx2("span", { className: "inline-flex shrink-0 items-center", children: endAdornment })
+          ] })
+        ] })
+      }
+    );
+  }
+);
 export {
+  ActionChip,
   Chip
 };

package/docs/action-chip-inventory.md

@@ -0,0 +1,21 @@
+# DS-20 host inventory
+
+Read-only inventory captured 29 October 2026. No Payload source is changed by
+this package work.
+
+| Host                         | Current composition                                                                      | Required behaviour                                                                                   |
+| ---------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `ManuscriptFilterChip.jsx`   | Div-root Chip with role, tab index, manual Enter/Space activation, TagNumber and Chevron | Native button ref/events, selected styling independent of popup expansion, count and adornment slots |
+| `ManuScriptsHome.jsx` Stages | Controlled Menu, selected status count and filter-active visual                          | Native Menu trigger; count/filter state stays with host                                              |
+| `ManuScriptsHome.jsx` sort   | Controlled Menu with dynamic sort label                                                  | Expansion visual without toggle-button semantics                                                     |
+| `ManuscriptSeriesFilter.jsx` | Controlled Menu with selected series count and selected filter visual                    | Forwarded trigger ref/ARIA/events; selection remains controlled by host                              |
+| `MetaDataHome.jsx` Status    | Menu trigger wraps Chip in a div, count is selected count or total                       | Candidate native trigger adoption, preserving the host's count policy                                |
+| `MetaDataHome.jsx` sort      | Menu trigger wraps a dynamic-label Chip in a div                                         | Candidate native trigger adoption                                                                    |
+
+Sources: audit round 2 README DS-20, review-1 section 3, review-3 R3-03;
+`payload-client/src/features/Manuscripts/components/ManuscriptFilterChip.jsx`,
+`ManuscriptSeriesFilter.jsx`, `elements/ManuScriptsHome.jsx`, and
+`features/Metadata/pages/MetaDataHome.jsx` in the read-only Payload checkout.
+
+The existing Chip root remains a div. Its removal button, callback composition,
+ref types and disabled semantics are a separate contract from an action trigger.

package/docs/action-chip.md

@@ -0,0 +1,85 @@
+# ActionChip
+
+`ActionChip` is a native button for compact filter actions and Menu/Popover
+triggers. The existing `Chip` remains a div with an optional removal button.
+
+```tsx
+import { ActionChip } from "@edux-design/chips";
+import { TagNumber } from "@edux-design/tags";
+import { Chevron } from "@edux-design/icons";
+import { Menu, MenuList, MenuItem } from "@edux-design/menus";
+
+<Menu
+  button={
+    <ActionChip
+      label="Stages"
+      selected={selectedStages.length > 0}
+      count={
+        selectedStages.length > 0 ? (
+          <TagNumber variant="brand" tone="solid">
+            {selectedStages.length}
+          </TagNumber>
+        ) : null
+      }
+      endAdornment={<Chevron aria-hidden="true" />}
+    />
+  }
+>
+  <MenuList>
+    <MenuItem onClick={chooseDraft}>Draft</MenuItem>
+  </MenuList>
+</Menu>;
+```
+
+The Menu clones its trigger and supplies popup ARIA, handlers and a composed
+button ref. Popover uses `<PopoverTrigger asChild><ActionChip ... /></PopoverTrigger>`.
+Both compositions retain native Enter/Space/click activation, handler cancellation
+with `event.preventDefault()`, disabled behaviour, Escape dismissal and focus
+restoration. No role, tab index or synthetic keyboard-to-click adapter is needed.
+
+| Prop                                  | Contract                                                                                     |
+| ------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `ref`                                 | `HTMLButtonElement`; Chip still accepts `HTMLDivElement`                                     |
+| `label`                               | Noninteractive React content; native `children` is the fallback when label is undefined      |
+| `count`                               | Noninteractive React content before label; host owns value, visibility and accessible naming |
+| `startAdornment`, `endAdornment`      | Noninteractive content, such as an icon or chevron                                           |
+| `selected`                            | Filter-applied visual and `data-selected="true"` only; never sets `aria-pressed`             |
+| `aria-expanded` / `data-state="open"` | Independently highlights an open popup                                                       |
+| `aria-pressed`                        | Optional native attribute only when the action is an actual toggle                           |
+| `disabled`                            | Native disabled button semantics and muted token colours                                     |
+| `type`                                | Native button type, default `"button"`; explicit submit/reset remain supported               |
+| `size`                                | `"default"` (40px minimum) or `"small"` (32px minimum), matching existing Chip geometry      |
+| Other native button props             | Forwarded, including ARIA, form attributes and events                                        |
+
+`onRemove`, `removeLabel` and `removeButtonProps` are prohibited by the public
+ActionChip type. Use `Chip` for removal. Do not place buttons, links, form fields,
+removable Chips or other interactive descendants in any label/count/adornment
+slot. Decorative icons should be hidden from assistive technology. Supply an
+accessible name when there is no visible text; for a terse count, an explicit
+`aria-label` can state the filter name and selected count together.
+
+The chip minimum heights intentionally remain component-owned 40px and the
+existing 32px spacing token; mapping to the control-size family would alter
+established compact filter geometry. Existing spacing, colours, shadows, radii
+and focus tokens are reused without changing the token package. The label
+truncates in a constrained parent while count and adornments remain visible.
+
+The host owns filter choices, loading/search, selection changes, popup state and
+counts. This component does not manage pressed/open state or emit separate state
+callbacks. The host should replace the old ManuscriptFilterChip's div keyboard
+adapter with ActionChip when it adopts a released package; see
+[action-chip-inventory.md](./action-chip-inventory.md) for the inspected hosts.
+
+Verification: `src/elements/ActionChip.test.tsx`, strict public fixtures in
+`test/action-chip-api.tsx`, CJS/SSR in `test/action-chip-public-runtime.cjs`,
+four strict-a11y stories, and `node packages/chips/test/action-chip.browser.mjs`.
+The browser suite compares both sizes against legacy Chip geometry in blue/teal,
+light/dark; checks native once-only pointer/Enter/Space activation, real overlay
+Escape/focus restoration, disabled state, and narrow long-label truncation.
+
+The Menu composition story counts only true `onOpenChange` requests. Menu owns
+its trigger opening policy, and may handle keyboard events before a native click
+is emitted. Child `onClick` is not an overlay-open notification contract. The
+standalone ActionChip tests separately verify one native click per pointer, Enter
+or Space activation. Keyboard story sequences await Escape focus restoration
+before sending the next activation key.

package/docs/removal.md

@@ -0,0 +1,26 @@
+# Removal, descriptions and focus
+
+`Chip` remains a static native div with a forwarded `HTMLDivElement` ref. Passing
+`onRemove` renders its existing native button. Set a specific `removeLabel`, such
+as `Remove AC9M3N01`.
+
+`removeButtonProps` forwards attributes, native handlers, style, className and an
+`HTMLButtonElement` ref to that same button. It adds no wrapper or tab stop. Use
+`aria-describedby` to associate host-owned context with the actual remove action;
+descriptions on an ancestor are not inherited. A visual tooltip can still use
+`TooltipTrigger asChild` around the Chip root.
+
+Chip owns the remove button's `type="button"`, `disabled`, accessible name and
+icon children. `type`, `disabled`, `aria-label`, `aria-labelledby` and `children`
+are excluded from the public slot props and cannot override those core semantics.
+The slot's click handler runs before `onRemove`; `event.preventDefault()` cancels
+removal. Click propagation is stopped, including when cancelled, so an ancestor
+does not also toggle the selection. A disabled Chip invokes neither click
+callback. Other native events, including keyboard and focus handlers, forward
+normally. Class names merge with the existing button presentation.
+
+Collection state and focus after removal belong to the host. Use the public
+button refs to focus the next enabled remove action, then the previous action,
+then a stable host control when the last chip disappears. Do not query private
+button markup or focus the noninteractive root. The Selection adoption story
+demonstrates this recipe with descriptions and keyboard/pointer removal.

package/package.json

@@ -1,36 +1,24 @@
 {
   "name": "@edux-design/chips",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "private": false,
   "sideEffects": [
     "**/*.css"
   ],
   "files": [
-    "dist"
+    "dist",
+    "docs",
+    "README.md",
+    "CHANGELOG.md"
   ],
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
-      "require": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.js"
     }
   },
-  "scripts": {
-    "lint": "eslint . --max-warnings 0",
-    "build": "tsup src/index.js --format esm,cjs --dts",
-    "dev": "tsup src/index.js --watch --format esm,cjs --dts",
-    "generate:component": "turbo gen react-component",
-    "check-types": "tsc --noEmit"
-  },
-  "devDependencies": {
-    "typescript": "^5.9.2",
-    "tailwindcss": "^4.1.12",
-    "postcss": "^8.5.6",
-    "tsup": "^8.5.0",
-    "@tailwindcss/cli": "^4.1.12",
-    "@tailwindcss/postcss": "^4.1.12"
-  },
   "dependencies": {
     "@edux-design/utils": "*",
     "@edux-design/icons": "*"