feat(book): add injection and popups categories to the component book (#12445)

Author: guanbinrui

apps/book/README.md

@@ -36,6 +36,27 @@ export default function Demo() {
 `import.meta.glob` in `src/registry.ts` picks it up automatically. The first path segment
 under `demos/` is the sidebar section (`foundation`, `components`, `icons`, `shared`, …).
 
+A section can have sub-categories one level deep: `demos/<section>/<group>/<name>.demo.tsx`
+(e.g. `demos/injection/twitter/Banner.demo.tsx`) renders under a "Twitter" sub-header inside the
+"Injection" section. `injection` is the only section that currently uses this.
+
+### Injection and Popups
+
+- `injection` demos the components each site adaptor (`packages/mask/content-script/site-adaptors/*`)
+  injects into a social platform's own page, one sub-category per platform. Most of the real
+  injection code is tightly coupled to the extension runtime (background RPC via the `#services`
+  subpath import, the live `activatedSiteAdaptorUI` global, DOM watchers) and can't run standalone
+  here. Where a component's pure-UI part could be cleanly separated from that coupling, it was
+  moved into `packages/injected-ui` — a small package with **one export per component, no barrel
+  `index.ts`** — and both the real injection code and this book import the same file from there
+  (see e.g. `packages/mask/content-script/components/GuideStep/index.tsx`, which now just computes
+  props from the real guide-progress state and renders `@masknet/injected-ui/GuideStep`). Only a
+  handful of components have been split out so far; the rest are left for follow-up.
+- `popups` demos a few self-contained presentational components from
+  `packages/mask/popups/components/*` (imported directly by relative path, since that package isn't
+  set up to be depended on by name). Anything that needs live wallet/RPC state, or that pulls in a
+  barrel file with unrelated modules, was left out — see the note in the PR that added this section.
+
 ## Deploy (Vercel)
 
 - Root Directory: `apps/book`

apps/book/package.json

@@ -10,6 +10,7 @@
   },
   "dependencies": {
     "@masknet/icons": "workspace:*",
+    "@masknet/injected-ui": "workspace:*",
     "@masknet/shared-base": "workspace:*",
     "@masknet/theme": "workspace:*",
     "@mui/icons-material": "9.2.0",

apps/book/src/components/Nav.tsx

@@ -1,4 +1,5 @@
-import { sections } from '../registry.ts'
+import { Fragment } from 'react'
+import { groupTitle, sections } from '../registry.ts'
 import { useMode } from '../providers.tsx'
 
 interface Props {
@@ -17,21 +18,33 @@ export function Nav({ current, onNavigate }: Props) {
                 </button>
             </div>
 
-            {sections.map((section) => (
-                <div key={section.id}>
-                    <div className="book-section-title">{section.title}</div>
-                    {section.entries.map((entry) => (
-                        <button
-                            type="button"
-                            key={entry.id}
-                            className="book-nav-link"
-                            data-active={entry.id === current}
-                            onClick={() => onNavigate(entry.id)}>
-                            {entry.name}
-                        </button>
-                    ))}
-                </div>
-            ))}
+            {sections.map((section) => {
+                let lastGroup: string | undefined
+                return (
+                    <div key={section.id}>
+                        <div className="book-section-title">{section.title}</div>
+                        {section.entries.map((entry) => {
+                            const showGroupHeader = entry.group !== lastGroup
+                            lastGroup = entry.group
+                            return (
+                                <Fragment key={entry.id}>
+                                    {showGroupHeader && entry.group ?
+                                        <div className="book-group-title">{groupTitle(entry.group)}</div>
+                                    :   null}
+                                    <button
+                                        type="button"
+                                        className="book-nav-link"
+                                        data-active={entry.id === current}
+                                        data-grouped={!!entry.group}
+                                        onClick={() => onNavigate(entry.id)}>
+                                        {entry.name}
+                                    </button>
+                                </Fragment>
+                            )
+                        })}
+                    </div>
+                )
+            })}
         </nav>
     )
 }

apps/book/src/demo.ts

@@ -15,11 +15,13 @@ export interface DemoModule {
 }
 
 export interface DemoEntry {
-    /** e.g. "components/ActionButton" */
+    /** e.g. "injection/twitter/Banner" */
     id: string
-    /** e.g. "components" */
+    /** e.g. "injection" */
     section: string
-    /** e.g. "ActionButton" */
+    /** e.g. "twitter", for demos nested one level under a section */
+    group?: string
+    /** e.g. "Banner" */
     name: string
     title: string
     description?: string

apps/book/src/demos/injection/facebook/Banner.demo.tsx

@@ -0,0 +1,30 @@
+import { useState } from 'react'
+import { FormControlLabel, Stack, Switch } from '@mui/material'
+import { Banner } from '@masknet/injected-ui/Banner'
+
+export const meta = {
+    title: 'Banner',
+    description:
+        '"Sign in with Mask" entry point injected into the compose box on Facebook (packages/injected-ui/src/Banner.tsx).',
+}
+
+export default function BannerFacebookDemo() {
+    const [connected, setConnected] = useState(false)
+
+    return (
+        <Stack spacing={2} sx={{ alignItems: 'flex-start' }}>
+            <FormControlLabel
+                control={<Switch checked={connected} onChange={(_, checked) => setConnected(checked)} />}
+                label="Persona already connected (hides the banner)"
+            />
+            <span
+                style={{
+                    display: 'block',
+                    padding: '0 16px',
+                    marginTop: 0,
+                }}>
+                <Banner nextStep={connected ? 'hidden' : { onClick: () => alert('open dashboard') }} />
+            </span>
+        </Stack>
+    )
+}

apps/book/src/demos/injection/facebook/PostDialogHint.demo.tsx

@@ -0,0 +1,43 @@
+import { useState } from 'react'
+import { Stack, Typography } from '@mui/material'
+import { PostDialogHint } from '@masknet/injected-ui/PostDialogHint'
+
+export const meta = {
+    title: 'PostDialogHint',
+    description:
+        'Mask badge injected next to the compose button on Facebook (packages/injected-ui/src/PostDialogHint.tsx), with the onboarding guide tip enabled.',
+}
+
+export default function PostDialogHintFacebookDemo() {
+    const [clicked, setClicked] = useState(0)
+    const [guideDismissed, setGuideDismissed] = useState(false)
+
+    return (
+        <Stack spacing={2} sx={{ alignItems: 'flex-start', paddingTop: '48px', paddingLeft: '48px' }}>
+            <Typography variant="body2" color="text.secondary">
+                Clicked {clicked} time(s){guideDismissed ? ' — guide dismissed' : ''}
+            </Typography>
+            <PostDialogHint
+                size={24}
+                tooltip={{ disabled: false, placement: 'top' }}
+                onHintButtonClicked={() => setClicked((c) => c + 1)}
+                guide={
+                    guideDismissed ? undefined : (
+                        {
+                            step: 1,
+                            total: 1,
+                            tip: 'Click here to have a quick start.',
+                            visible: true,
+                            onSkip: () => setGuideDismissed(true),
+                            onNext: () => setGuideDismissed(true),
+                            onTry: () => {
+                                setGuideDismissed(true)
+                                setClicked((c) => c + 1)
+                            },
+                        }
+                    )
+                }
+            />
+        </Stack>
+    )
+}

apps/book/src/demos/injection/minds/Banner.demo.tsx

@@ -0,0 +1,23 @@
+import { useState } from 'react'
+import { FormControlLabel, Stack, Switch } from '@mui/material'
+import { Banner } from '@masknet/injected-ui/Banner'
+
+export const meta = {
+    title: 'Banner',
+    description:
+        '"Sign in with Mask" entry point injected into the compose box on Minds (packages/injected-ui/src/Banner.tsx). Minds uses the Minds-branded icon via `iconType="minds"`.',
+}
+
+export default function BannerMindsDemo() {
+    const [connected, setConnected] = useState(false)
+
+    return (
+        <Stack spacing={2} sx={{ alignItems: 'flex-start' }}>
+            <FormControlLabel
+                control={<Switch checked={connected} onChange={(_, checked) => setConnected(checked)} />}
+                label="Persona already connected (hides the banner)"
+            />
+            <Banner iconType="minds" nextStep={connected ? 'hidden' : { onClick: () => alert('open dashboard') }} />
+        </Stack>
+    )
+}

apps/book/src/demos/injection/minds/PostDialogHint.demo.tsx

@@ -0,0 +1,27 @@
+import { useState } from 'react'
+import { Stack, Typography } from '@mui/material'
+import { PostDialogHint } from '@masknet/injected-ui/PostDialogHint'
+
+export const meta = {
+    title: 'PostDialogHint',
+    description:
+        'Mask badge injected next to the compose button on Minds (packages/injected-ui/src/PostDialogHint.tsx). Minds disables the onboarding guide tip for this entry point.',
+}
+
+export default function PostDialogHintMindsDemo() {
+    const [clicked, setClicked] = useState(0)
+
+    return (
+        <Stack spacing={2} sx={{ alignItems: 'flex-start' }}>
+            <Typography variant="body2" color="text.secondary">
+                Clicked {clicked} time(s)
+            </Typography>
+            <PostDialogHint
+                size={17}
+                iconType="minds"
+                tooltip={{ disabled: true }}
+                onHintButtonClicked={() => setClicked((c) => c + 1)}
+            />
+        </Stack>
+    )
+}

apps/book/src/demos/injection/shared/GuideStep.demo.tsx

@@ -0,0 +1,49 @@
+import { useState } from 'react'
+import { Button, Stack, Typography } from '@mui/material'
+import { GuideStep } from '@masknet/injected-ui/GuideStep'
+
+export const meta = {
+    title: 'GuideStep',
+    description:
+        'Onboarding tooltip overlay injected next to a highlighted element on every site adaptor (packages/injected-ui/src/GuideStep.tsx). Used cross-platform: the wallet/app toolbox hints, PostDialogHint, and the setup wizard all wrap their target in this.',
+}
+
+const TIPS = [
+    'Explore multi-chain dApps.',
+    'Connect and switch between your wallets.',
+    'Click here to have a quick start.',
+]
+const TOTAL = TIPS.length
+
+export default function GuideStepDemo() {
+    const [step, setStep] = useState(1)
+    const [finished, setFinished] = useState(false)
+
+    return (
+        <Stack spacing={2} sx={{ alignItems: 'flex-start', paddingTop: '48px', paddingLeft: '48px' }}>
+            <Typography variant="body2" color="text.secondary">
+                {finished ? 'Tour dismissed.' : `Step ${step} of ${TOTAL}`}
+            </Typography>
+            <Button
+                variant="outlined"
+                onClick={() => {
+                    setStep(1)
+                    setFinished(false)
+                }}>
+                Restart tour
+            </Button>
+            <GuideStep
+                total={TOTAL}
+                step={step}
+                tip={TIPS[step - 1]}
+                visible={!finished}
+                onSkip={() => setFinished(true)}
+                onNext={() => setStep((s) => Math.min(s + 1, TOTAL))}
+                onTry={() => setFinished(true)}>
+                <Button variant="contained" sx={{ pointerEvents: 'none' }}>
+                    Highlighted element
+                </Button>
+            </GuideStep>
+        </Stack>
+    )
+}

apps/book/src/demos/injection/twitter/Banner.demo.tsx

@@ -0,0 +1,23 @@
+import { useState } from 'react'
+import { FormControlLabel, Stack, Switch } from '@mui/material'
+import { Banner } from '@masknet/injected-ui/Banner'
+
+export const meta = {
+    title: 'Banner',
+    description:
+        '"Sign in with Mask" entry point injected into the compose box on X/Twitter (packages/injected-ui/src/Banner.tsx). Hidden once a persona is already linked to the account.',
+}
+
+export default function BannerTwitterDemo() {
+    const [connected, setConnected] = useState(false)
+
+    return (
+        <Stack spacing={2} sx={{ alignItems: 'flex-start' }}>
+            <FormControlLabel
+                control={<Switch checked={connected} onChange={(_, checked) => setConnected(checked)} />}
+                label="Persona already connected (hides the banner)"
+            />
+            <Banner nextStep={connected ? 'hidden' : { onClick: () => alert('open dashboard') }} />
+        </Stack>
+    )
+}