@edux-design/chips 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @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

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.
 
 ---
 
@@ -37,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>
   );
 }
@@ -45,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.
 
@@ -74,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,3 +1,5 @@
+import React from 'react';
+
 /**
  * Token-driven chip that composes existing primitives (i.e. TagNumber) inside.
  *
@@ -24,4 +26,23 @@ type ChipProps = React.HTMLAttributes<HTMLDivElement> & {
     removeButtonProps?: Omit<React.ComponentPropsWithRef<"button">, "type" | "disabled" | "aria-label" | "aria-labelledby" | "children">;
 };
 
-export { Chip };
+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 { ActionChip, Chip };

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import React from 'react';
+
 /**
  * Token-driven chip that composes existing primitives (i.e. TagNumber) inside.
  *
@@ -24,4 +26,23 @@ type ChipProps = React.HTMLAttributes<HTMLDivElement> & {
     removeButtonProps?: Omit<React.ComponentPropsWithRef<"button">, "type" | "disabled" | "aria-label" | "aria-labelledby" | "children">;
 };
 
-export { Chip };
+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 { 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);
@@ -111,7 +112,7 @@ var Chip = (0, import_react.forwardRef)(function Chip2({
             onClick: (event) => {
               event.stopPropagation();
               if (disabled) return;
-              onRemoveClick == null ? void 0 : onRemoveClick(event);
+              onRemoveClick?.(event);
               if (!event.defaultPrevented) onRemove(event);
             },
             className: (0, import_utils.cx)(
@@ -131,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

@@ -76,7 +76,7 @@ var Chip = forwardRef(function Chip2({
             onClick: (event) => {
               event.stopPropagation();
               if (disabled) return;
-              onRemoveClick == null ? void 0 : onRemoveClick(event);
+              onRemoveClick?.(event);
               if (!event.defaultPrevented) onRemove(event);
             },
             className: cx(
@@ -96,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edux-design/chips",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": false,
   "sideEffects": [
     "**/*.css"