@liberfi.io/ui-tokens 0.1.190 → 1.0.0

package/README.md

@@ -91,6 +91,39 @@ import { SearchWidget } from "@liberfi.io/ui-tokens";
 | `PulseMigratedListWidget`     | Widget | Migrated tokens pulse feed.      |
 | `PulseFinalStretchListWidget` | Widget | Final-stretch tokens pulse feed. |
 
+### Components — Shared primitives
+
+| Export               | Kind | Description                                                                |
+| -------------------- | ---- | -------------------------------------------------------------------------- |
+| `TraderTagBadge`     | UI   | Classification chip for a single trader tag (`kol`, `smart`, `sniper`, …). |
+| `TraderTagBadgeList` | UI   | Row of trader tags with max-visible + overflow counter.                    |
+| `HolderTagBadge`     | UI   | Classification chip for a single holder tag (same palette as trader tags). |
+| `HolderTagBadgeList` | UI   | Row of holder tags with max-visible + overflow counter.                    |
+
+### Components — Token Detail
+
+Token-detail widgets follow the `*.ui.tsx` / `*.script.ts` / `*.widget.tsx` triad. Every script layer calls `@liberfi.io/react` hooks only; UI layers are pure presentational and driven by props. The header composes the basic-info strip by default — pass `dataStrip={null}` to hide it.
+
+| Export                            | Kind   | Description                                                                                                                                 |
+| --------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `TokenDetailHeaderWidget`         | Widget | Live-updating header: avatar, symbol / name, copy-address, slot for favorite / share actions, and an injectable data strip.                 |
+| `TokenBasicInfoWidget`            | Widget | Compact strip: price, market cap, volume, holders, social media. Consumes `useTokenQuery` + `useTokenSubscription`.                         |
+| `TokenPriceWidget`                | Widget | Live price + 24h change badge.                                                                                                              |
+| `TokenMarketCapWidget`            | Widget | Market cap / liquidity / age summary.                                                                                                       |
+| `TokenVolumeWidget`               | Widget | 24h volume / trades / traders summary.                                                                                                      |
+| `TokenHoldersCountWidget`         | Widget | Holder count + top-10 / top-100 ratio summary.                                                                                              |
+| `TokenSocialMediaWidget`          | Widget | Row of social-media icon links (website, twitter, telegram, discord, …).                                                                    |
+| `TokenHoldersListWidget`          | Widget | Paginated token-holders table (**Phase 3**): `sortBy` selector (`holdingUsd` / `lastActiveAt`), holder tags, first-held-at, last-active-at. |
+| `TokenActivitiesListWidget`       | Widget | Paginated token-activities table (**Phase 3**): `sortBy` selector, type filter, trader tags, gas fee.                                       |
+| `TokenTradersOverviewWidget`      | Widget | Unique-traders card with buy / sell split and progress bar.                                                                                 |
+| `TokenTransactionsOverviewWidget` | Widget | Tx-count card with buy / sell split and progress bar.                                                                                       |
+| `TokenVolumesOverviewWidget`      | Widget | USD-volume card with buy / sell split and progress bar.                                                                                     |
+| `TokenSecurityWidget`             | Widget | Security flags from `useTokenSecurityQuery` (transfer fee / freezable / closable / …) + optional external auditor link.                     |
+| `TokenAboutWidget`                | Widget | Name / symbol / human-readable description section.                                                                                         |
+| `TokenLiquiditiesWidget`          | Widget | DEX liquidity breakdown with per-pool TVL and collapse-at-N support.                                                                        |
+| `TokenCexListingWidget`           | Widget | CEX listings chips. Data is caller-supplied (the `Token` domain type does not model CEX listings).                                          |
+| `TokenCategoriesWidget`           | Widget | Category chips sourced from `token.tags`.                                                                                                   |
+
 ### Hooks
 
 | Export              | Description                                                                                       |
@@ -137,9 +170,58 @@ function Sidebar() {
 }
 ```
 
+### Composing the token-detail page
+
+```tsx
+import {
+  TokenDetailHeaderWidget,
+  TokenHoldersListWidget,
+  TokenActivitiesListWidget,
+  TokenSecurityWidget,
+  TokenAboutWidget,
+  TokenLiquiditiesWidget,
+  TokenCategoriesWidget,
+  TokenTradersOverviewWidget,
+  TokenTransactionsOverviewWidget,
+  TokenVolumesOverviewWidget,
+} from "@liberfi.io/ui-tokens";
+
+function TokenDetailPage({
+  chain,
+  address,
+}: {
+  chain: Chain;
+  address: string;
+}) {
+  return (
+    <div className="flex flex-col gap-4">
+      <TokenDetailHeaderWidget chain={chain} address={address} />
+
+      <div className="grid grid-cols-1 gap-4 lg:grid-cols-3">
+        <TokenTradersOverviewWidget chain={chain} address={address} />
+        <TokenTransactionsOverviewWidget chain={chain} address={address} />
+        <TokenVolumesOverviewWidget chain={chain} address={address} />
+      </div>
+
+      <TokenActivitiesListWidget chain={chain} address={address} />
+      <TokenHoldersListWidget chain={chain} address={address} />
+
+      <div className="grid grid-cols-1 gap-4 lg:grid-cols-2">
+        <TokenAboutWidget chain={chain} address={address} />
+        <TokenSecurityWidget chain={chain} address={address} />
+        <TokenCategoriesWidget chain={chain} address={address} />
+        <TokenLiquiditiesWidget chain={chain} address={address} />
+      </div>
+    </div>
+  );
+}
+```
+
 ## Future Improvements
 
 - Add tab system (Discover / Favorite / View) for the empty-state content when no keyword is entered.
 - Support sort and filter controls in search result headers.
 - Add chain selector to scope search to a specific chain.
 - Support custom `atomWithStorage` storage adapter for search history (e.g. server-side persistence).
+- Token-detail widgets: add skeleton loading states that match the final layout.
+- Token-holders list: wire a real-time WebSocket channel once the server exposes one (currently refreshes via pagination).