@ai-matrx/tap-target 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## 0.1.0 — 2026-08-29
+
+- Created the package, ported verbatim from the Matrx frontend tap-target
+  system (`components/icons/TapTargetButton.tsx` + `tap-buttons.tsx` +
+  `TapTargetLabeled.tsx` and the `.matrx-tap-*` block of `app/globals.css`):
+  the 44×44 invisible ring / 28px pill geometry (32/20px group geometry),
+  glass/transparent/solid/destructive/group variants, inline labels, the
+  button/label/link trigger resolver, tooltip wiring, the ref-forwarding
+  `Wrap` resolver required for Radix `asChild`, and ~60 pre-composed
+  one-tag buttons.
+- Coupling inversions (the only behavior deltas vs. the original):
+  - `next/link` → an injectable link component: module-level
+    `setTapTargetLinkComponent(Component)` plus a per-instance
+    `linkComponent` prop; internal hrefs fall back to a plain `<a>` when
+    nothing is registered; external href behavior (`target="_blank"`,
+    `rel="noopener noreferrer"`) unchanged. The registration lives in a
+    `Symbol.for` slot on `globalThis` so it is shared across the `.` /
+    `./buttons` bundles and the ESM/CJS boundary.
+  - `cn` from `@/lib/utils` → a tiny local class join, no dependency.
+  - `@/components/ui/tooltip` → inlined Radix wrapper on the
+    `@radix-ui/react-tooltip` dependency; the host-specific
+    `useNestedPortalContainer` is dropped (content portals to
+    `document.body`). `TooltipProvider` is re-exported for host mounting.
+- **The CSS ships as part of the package**: the `.matrx-tap-*` geometry +
+  press-feedback block is exported as `./styles.css` — import once at app
+  root.
+- Subpaths: `.` (primitives + `TapTargetLabeled` + link registration),
+  `./buttons` (the pre-composed set, opt-in), `./styles.css`,
+  `./package.json`.
+- Peer `react >= 18`; dependency `@radix-ui/react-tooltip`. ESM + CommonJS
+  with `"use client"` stamped on built chunks; the release gate installs the
+  packed tarball into an empty project, loads both subpaths through both
+  `import` and `require`, asserts `dist/styles.css` exists and resolves, and
+  proves the link registration crosses the ESM/CJS boundary.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI Matrix Engine
+
+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,127 @@
+# @ai-matrx/tap-target
+
+The AI Matrx tap-target button system: an **invisible 44×44 touch ring** over a
+**32×32 visible pill** (28px pill inside the ring; 32/20px in the slim group
+geometry), with press feedback, mobile tap hygiene (no 300ms delay, no iOS gray
+flash), and correct **ref forwarding for Radix `asChild` triggers**.
+
+- **Primitives** — `TapTargetButton` (glass), `TapTargetButtonTransparent`,
+  `TapTargetButtonSolid`, `TapTargetButtonDestructive`,
+  `TapTargetButtonForGroup` + `TapTargetButtonGroup`, and the
+  `TapTargetLabeled` caption wrapper.
+- **~60 pre-composed buttons** — `BugTapButton`, `PlusTapButton`,
+  `TrashTapButton`, … one import, one tag, zero configuration, all glyphs
+  inlined. Opt-in via the `./buttons` subpath.
+- Every button can be a **button, label, or link** (`as="label"`, `href`),
+  carries automatic **tooltip wiring** from `ariaLabel`, and supports an
+  inline caption (`label`) that widens the pill.
+
+```bash
+npm install @ai-matrx/tap-target
+```
+
+Peer: `react >= 18`. `@radix-ui/react-tooltip` is a regular dependency
+(small and behavior-critical — tooltips are part of the product).
+
+## Setup — two one-time steps
+
+**1. Import the stylesheet once at your app root. The CSS is part of the
+product** — the 44×44 ring / pill geometry and press feedback live in it, and
+nothing renders correctly without it:
+
+```tsx
+// app/layout.tsx (or your root entry)
+import "@ai-matrx/tap-target/styles.css";
+```
+
+Tailwind users migrating from the in-repo Matrx copy can keep their existing
+`globals.css` `.matrx-tap-*` block until the C9 swap removes it — the rules are
+identical; just don't load both forever.
+
+**2. Mount a tooltip provider near the root** (skip if your app already mounts
+`@radix-ui/react-tooltip`'s provider):
+
+```tsx
+import { TooltipProvider } from "@ai-matrx/tap-target";
+
+<TooltipProvider delayDuration={300}>{children}</TooltipProvider>
+```
+
+## Link component registration
+
+`href` on any tap button renders a link. External hrefs (`http(s):`, `mailto:`,
+`tel:`) always render `<a target="_blank" rel="noopener noreferrer">`. Internal
+hrefs render through your router's link component — register it once at
+startup:
+
+```tsx
+import Link from "next/link";
+import { setTapTargetLinkComponent } from "@ai-matrx/tap-target";
+
+setTapTargetLinkComponent(Link); // e.g. in a client boot component
+```
+
+Without a registration, internal hrefs fall back to a plain `<a>` (still a
+working link — no prefetch, no client-side routing). A per-instance override
+is also available: `<TapTargetButton href="/tasks" linkComponent={Link} />`.
+
+## Usage
+
+```tsx
+import { TapTargetButton, TapTargetButtonGroup, TapTargetButtonForGroup } from "@ai-matrx/tap-target";
+import { PlusTapButton, TrashTapButton } from "@ai-matrx/tap-target/buttons";
+
+// Pre-composed (preferred): one tag, tooltip auto-derives from ariaLabel
+<PlusTapButton onClick={add} ariaLabel="Add a task" />
+
+// Variants: glass (default) | transparent | solid | group
+<TrashTapButton variant="solid" bgColor="bg-destructive" iconColor="text-destructive-foreground" />
+
+// Links
+<PlusTapButton href="/tasks/new" ariaLabel="New task" />
+
+// Inline caption (widens the pill, tooltip off — the label self-describes)
+<PlusTapButton label="Add" />
+
+// Grouped slim buttons in one shared glass shell
+<TapTargetButtonGroup>
+  <TapTargetButtonForGroup ariaLabel="Undo" icon={<UndoIcon />} />
+  <TapTargetButtonForGroup ariaLabel="Redo" icon={<RedoIcon />} />
+</TapTargetButtonGroup>
+
+// Custom glyph via the primitive
+<TapTargetButton ariaLabel="Custom" icon={<MyIcon className="h-4 w-4" />} />
+```
+
+Refs forward to the underlying `<button>`, so every button works as a Radix
+`asChild` trigger (DropdownMenu, Popover, Tooltip, …):
+
+```tsx
+<DropdownMenuTrigger asChild>
+  <MoreHorizontalTapButton />
+</DropdownMenuTrigger>
+```
+
+## Subpaths
+
+| Subpath | What it is |
+|---|---|
+| `.` | Primitives, `TapTargetLabeled`, link registration, tooltip re-exports. |
+| `./buttons` | The ~60 pre-composed buttons (heavy — every glyph inlined; opt-in). |
+| `./styles.css` | The REQUIRED geometry/feedback stylesheet — import once at app root. |
+| `./package.json` | The manifest. |
+
+## Styling notes
+
+- Geometry and press feedback come from `styles.css` (`.matrx-tap-*`). To
+  retune every tap button, that file is the single source of truth — never
+  per-button size overrides.
+- Variant **decoration** uses Tailwind-style utility classes on the pill
+  (`bg-primary`, `hover:bg-muted`, `text-foreground`, and the Matrx
+  `matrx-glass-thin-border` / `matrx-glass-interactive` glass classes). In a
+  Tailwind app these resolve against your theme tokens; make sure your
+  Tailwind build scans this package (Tailwind v4:
+  `@source "../node_modules/@ai-matrx/tap-target";`) and provide the two
+  `matrx-glass-*` classes (or accept an undecorated glass pill).
+- Never wrap a tap button in extra `p-*`/`m-*`/`gap-*` — the invisible ring
+  already reserves the spacing.