@meddleware/dao-ui 0.1.7 → 0.1.8

package/README.md

@@ -0,0 +1,94 @@
+# @meddleware/dao-ui
+
+The **Meddleware DAO console** — a standalone Vue 3 SPA (and embeddable library) that surfaces the
+platform's on-chain state on Sui: treasury balance, commission policy, the community access gates the
+treasury controls, and a live feed of access-gate activity.
+
+Deployed at `sui-dao.meddleware.co.uk` and also embedded inline in the tools hub
+(`sui.meddleware.co.uk`) as the default view.
+
+## What it shows
+
+The console is **read-only today** — no wallet connection is required to view any data. It reads
+directly from Sui via a bare RPC client. Five tabs:
+
+| Tab | Content |
+| --- | --- |
+| **Overview** | Treasury balance + commission rate, platform activity counters (active gates, accesses minted/consumed), and a recent-activity feed. |
+| **Treasury** | Commission rate (bps), current SUI balance, treasury address, and the table of **Community Gates** the treasury controls (name, price, object id). |
+| **Proposals** | Fundraising / governance proposals. **Placeholder** until the `vault_dao` on-chain module ships — shows an empty state today (see [Roadmap](#roadmap)). |
+| **Governance** | Platform parameters (commission rate, the on-chain 10% / 1000-bps hard cap, treasury address) and an **Admin Actions** panel that detects whether the connected wallet holds a `PlatformAdminCap`. Controls light up only for cap holders (implementation pending). |
+| **History** | Paginated on-chain event log (access sold / used / burned) with explorer links per address and transaction. |
+
+## How gate discovery works
+
+Gates are discovered by **`AdminCap` ownership**, not by events:
+
+1. Read the treasury address from the `PlatformConfig` shared object.
+2. List `access_gate::AdminCap` objects owned by the treasury.
+3. Fetch each `Gate` shared object referenced by its `AdminCap.gate_id`.
+
+This is deliberately **resilient to event pruning** — testnet fullnodes prune old events (including
+the one-time `GateCreatedEvent`) after ~3 months, so event-based gate counting is unreliable. The
+`AdminCap`→`Gate` path always reflects live on-chain reality. See
+[`src/composables/useGates.ts`](src/composables/useGates.ts).
+
+## Commission model
+
+Commission is charged on every NFT access purchase and enforced on-chain by the `access_gate`
+package: `commission_bps / 10000 × price` routes to the treasury; the remainder goes to the gate
+operator. `commission_bps` is read live from `PlatformConfig`; the on-chain hard cap is 1000 bps
+(10%).
+
+## Configure (build-time `VITE_*`)
+
+All values have working testnet defaults; override per network for mainnet.
+
+| Var | Meaning |
+| --- | --- |
+| `VITE_NETWORK` | `testnet` (default) or `mainnet` |
+| `VITE_RPC_TESTNET` / `VITE_RPC_MAINNET` | Sui RPC URL override |
+| `VITE_ACCESS_GATE_PACKAGE_ID_{NET}` | Published `access_gate` package id (governs which events/objects are queried) |
+| `VITE_PLATFORM_CONFIG_ID_{NET}` | `PlatformConfig` shared-object id (commission + treasury) |
+
+Mainnet package/config ids are empty until deployment; set them via the `_MAINNET` vars — no code
+change required.
+
+## Develop
+
+```sh
+npm install
+npm run dev          # vite dev server
+npm run type-check   # vue-tsc --noEmit
+npm test             # vitest
+```
+
+## Build
+
+```sh
+npm run build        # vue-tsc + vite → dist/
+docker build -t dao-ui .
+```
+
+## Use as a library
+
+The package exports the core view so the dashboard (or any host) can render it inline against a
+shared wallet:
+
+```ts
+import { DaoView } from '@meddleware/dao-ui'
+```
+
+`DaoView` imports its own scoped stylesheet (`styles/qt.css`), so no consumer needs to import dao-ui
+CSS separately. See [CLAUDE.md](CLAUDE.md) for the dual app+library architecture.
+
+## Roadmap
+
+- **`vault_dao` on-chain module** — proposals and governance are stubbed
+  ([`src/composables/useProposals.ts`](src/composables/useProposals.ts) returns an empty list; the
+  Governance admin panel detects the cap but has no actions yet). When `vault_dao` ships, the
+  `Proposal` type and composable return shapes are kept stable so the UI wiring is unchanged.
+
+## License
+
+BSD Zero Clause License (`0BSD`). See [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@meddleware/dao-ui",
-  "version": "0.1.7",
+  "version": "0.1.8",
+  "homepage": "https://docs.meddleware.co.uk/blockchain/sui/dao/",
   "description": "Meddleware DAO console — treasury overview, proposals, and governance on Sui.",
   "author": "Meddleware <dev@meddleware.co.uk>",
   "license": "0BSD",

package/src/App.vue

@@ -6,6 +6,7 @@ import { NETWORK } from './config.js'
 import DaoView from './DaoView.vue'
 
 const { mode, set } = useColorMode('dark')
+const DOCS_URL = import.meta.env.VITE_DOCS_URL || 'https://docs.meddleware.co.uk/blockchain/sui/dao/'
 </script>
 
 <template>
@@ -22,7 +23,7 @@ const { mode, set } = useColorMode('dark')
 
     <DaoView style="flex: 1; min-height: 0" />
 
-    <AppFooter />
+    <AppFooter :docs-url="DOCS_URL" />
   </div>
 </template>
 

package/src/components/AmountCell.vue

@@ -1,4 +1,6 @@
 <script setup lang="ts">
+// Formats a MIST bigint as human SUI (4 dp, trimming trailing zeros below that),
+// rendering "—" for null. Display-only; never source-of-truth for accounting.
 defineProps<{
   mist: bigint | null
   symbol?: string

package/src/components/DataTable.vue

@@ -1,4 +1,6 @@
 <script setup lang="ts">
+// Scrollable table shell with a `head` slot (header cells) and default slot (rows).
+// Renders the `empty` message when no rows are provided.
 defineProps<{ empty?: string }>()
 
 const slots = defineSlots<{

package/src/components/Panel.vue

@@ -1,4 +1,5 @@
 <script setup lang="ts">
+// Titled content panel — the console's basic surface primitive. Optional heading + default slot.
 defineProps<{ title?: string }>()
 </script>
 

package/src/components/ProposalRow.vue

@@ -1,4 +1,6 @@
 <script setup lang="ts">
+// Renders one fundraising/governance proposal: status badge, progress toward target,
+// and epochs-left. The Contribute button is disabled until the vault_dao module ships.
 import { computed } from 'vue'
 import type { Proposal } from '../composables/useProposals.js'
 

package/src/components/StatusBar.vue

@@ -1,4 +1,6 @@
 <script setup lang="ts">
+// Bottom status bar: network + health dot (error-driven), current epoch, and a
+// relative "refreshed Ns ago" timestamp. Purely presentational.
 import { computed } from 'vue'
 import { NETWORK } from '../config.js'
 

package/src/components/TabBar.vue

@@ -1,4 +1,6 @@
 <script setup lang="ts">
+// Bespoke raised-tab navigation for the console (v-model + typed tabs). Deliberately
+// distinct from the shared @meddleware/ui tab styling — the desktop-app look is intentional.
 export interface Tab {
   id: string
   label: string

package/src/composables/usePlatformConfig.ts

@@ -1,3 +1,6 @@
+// Reads the PlatformConfig shared object once on mount and exposes the treasury
+// address + commission rate (bps). Source of truth for the commission model and for
+// whose AdminCaps the gate discovery (useGates) looks up.
 import { ref, onMounted } from 'vue'
 import { getSuiClient } from '../wallet.js'
 import { CONFIG_ID } from '../config.js'

package/src/composables/useTreasury.ts

@@ -1,3 +1,5 @@
+// Reads the SUI balance of the treasury address. Reactive to the address getter so it
+// refetches when usePlatformConfig resolves; clears to null while the address is unknown.
 import { ref, watch } from 'vue'
 import { getSuiClient } from '../wallet.js'
 

package/src/config.ts

@@ -1,3 +1,6 @@
+// Build-time configuration. All chain ids are read from VITE_* env with working
+// testnet defaults; mainnet ids stay empty until deployment (set the _MAINNET vars —
+// no code change needed). PACKAGE_ID / CONFIG_ID / RPC_URL resolve to the active network.
 export type Network = 'testnet' | 'mainnet'
 
 export const NETWORK: Network = (import.meta.env.VITE_NETWORK as Network) || 'testnet'

package/src/index.ts

@@ -1 +1,3 @@
+// Library entry point. Hosts (e.g. the dashboard) import DaoView to render the DAO
+// console inline against a shared wallet. DaoView self-imports its scoped qt.css.
 export { default as DaoView } from './DaoView.vue'

package/src/main.ts

@@ -1,3 +1,6 @@
+// Standalone SPA bootstrap. Loads the design-token + ui base stylesheets and the
+// console's qt.css, then mounts the App shell. (The library path — src/index.ts —
+// bypasses this and relies on DaoView's own scoped qt.css import instead.)
 import '@meddleware/design-tokens/tokens.css'
 import '@meddleware/ui/base.css'
 import './styles/qt.css'

package/src/tabs/HistoryTab.vue

@@ -1,4 +1,6 @@
 <script setup lang="ts">
+// History tab: paginated on-chain access-gate event log (sold / used / burned) with
+// per-row explorer links. Data comes from useDaoEvents (pruning-tolerant, merged feed).
 import { ref, computed } from 'vue'
 import DataTable from '../components/DataTable.vue'
 import { useDaoEvents } from '../composables/useDaoEvents.js'

package/src/tabs/OverviewTab.vue

@@ -1,4 +1,6 @@
 <script setup lang="ts">
+// Overview tab: treasury balance + commission, platform activity counters (active gates,
+// accesses minted/consumed derived from the event feed), and a recent-activity list.
 import { computed } from 'vue'
 import Panel from '../components/Panel.vue'
 import AmountCell from '../components/AmountCell.vue'

package/src/tabs/ProposalsTab.vue

@@ -1,4 +1,6 @@
 <script setup lang="ts">
+// Proposals tab. Lists proposals via useProposals (currently a stub returning []),
+// showing an empty state until the on-chain vault_dao module lands.
 import ProposalRow from '../components/ProposalRow.vue'
 import { useProposals } from '../composables/useProposals.js'
 import { useEpoch } from '../composables/useEpoch.js'

package/src/tabs/TreasuryTab.vue

@@ -1,4 +1,6 @@
 <script setup lang="ts">
+// Treasury tab: commission rate + live SUI balance + treasury address, plus the table
+// of Community Gates the treasury controls (discovered via AdminCap ownership).
 import { computed } from 'vue'
 import Panel from '../components/Panel.vue'
 import AmountCell from '../components/AmountCell.vue'