Skip to content

Commit 61e5e9e

Browse files
authored
feat: complete public sharing cards and verified developer documentation
Add generated PNG metadata, original repository artwork, refreshed documentation and read-only verification CI. Run 36263931953 passed full workspace/browser checks; generated image and captures were downloaded and inspected. Existing search test needed a retry; sharing checks passed. Preserve credentials, dependencies, source-only package status and unofficial attribution.
1 parent 42c8e9b commit 61e5e9e

11 files changed

Lines changed: 265 additions & 52 deletions

File tree

‎.github/workflows/verification.yml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
name: Workspace verification
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches: [main]
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: read
11+
12+
concurrency:
13+
group: verify-${{ github.workflow }}-${{ github.ref }}
14+
cancel-in-progress: true
15+
16+
jobs:
17+
verify:
18+
runs-on: ubuntu-latest
19+
timeout-minutes: 25
20+
env:
21+
CI: "true"
22+
NEXT_TELEMETRY_DISABLED: "1"
23+
steps:
24+
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
25+
with:
26+
persist-credentials: false
27+
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
28+
with:
29+
node-version: "22"
30+
- name: Activate the repository-pinned pnpm
31+
run: corepack enable
32+
- name: Frozen dependency installation
33+
run: pnpm install --frozen-lockfile
34+
- name: Sharing source contract
35+
run: node --test scripts/social-metadata.test.mjs
36+
- name: Lint
37+
run: pnpm lint
38+
- name: Type checks
39+
run: pnpm typecheck
40+
- name: Production build
41+
run: pnpm build
42+
- name: Install Chromium
43+
run: pnpm --dir apps/web exec playwright install --with-deps chromium
44+
- name: Browser and rendered-image verification
45+
run: pnpm test:e2e
46+
- name: Retain synthetic browser evidence
47+
if: always()
48+
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
49+
with:
50+
name: ui-browser-evidence-${{ github.sha }}
51+
path: apps/web/test-results/
52+
if-no-files-found: ignore
53+
retention-days: 14

‎AGENTS.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,16 +35,20 @@ Run from the repository root:
3535
pnpm lint
3636
pnpm typecheck
3737
pnpm build
38+
pnpm test:e2e
39+
node --test scripts/social-metadata.test.mjs
3840
```
3941

4042
For UI changes, also inspect the component's Preview and Source tabs, Install and Import examples, `/lab`, keyboard behavior, light/dark modes, narrow screens, and RTL. `pnpm format` writes files; avoid unrelated formatting churn.
4143

42-
There is no root unit-test or E2E script at this revision. Do not invent `pnpm test`, report manual inspection as automated coverage, or claim a build proves accessibility. State which checks ran, their results, and any environment limitation.
44+
There is no root unit-test script named `test`; the root does define `test:e2e`. Do not invent `pnpm test`, report manual inspection as automated coverage, or claim a build proves accessibility. The standalone social-metadata check validates source invariants, not a rendered HTTP response. State which checks ran, their results, and any environment limitation.
4345

4446
## Documentation and handoff
4547

4648
Keep README.md and CONTRIBUTING.md consistent with the manifests. Keep CLAUDE.md as a pointer to this file rather than a competing policy. Preserve attribution to shadcn/ui, Base UI, TypeSafe-inspired branding, and the OpenCoven layout inspiration; do not imply vendor endorsement.
4749

50+
Read `docs/discovery/README.md` for sharing and screenshot guidance. The generated OG route must use public editorial copy only, never request content, credentials, or live model calls. Preserve existing per-page metadata and do not canonicalize all routes to the homepage.
51+
4852
`repository-metadata.json` records intended GitHub About text/topics only. Applying it requires a separate authorized GitHub settings action; editing the file alone does not publish topics. Do not create release tags, publish packages, change licensing, or change repository visibility unless explicitly requested.
4953

5054
<!-- BEGIN:nextjs-agent-rules -->

‎README.md‎

Lines changed: 51 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -2,96 +2,103 @@
22

33
Reusable React components and interactive interface patterns for TypeSafe AI projects, built with shadcn/ui, Base UI, and Tailwind CSS.
44

5-
**Small parts. Clear interfaces.** An independent community project maintained under `TypeSafeAI`, not an official TypeSafe AI component library or SDK.
5+
**Small parts. Clear interfaces.** This is an independent community project under `TypeSafeAI`, not an official TypeSafe AI component library or SDK. The community organization was created by VC Moderator [@BunsDev](https://github.com/BunsDev).
66

7-
[Contributing](CONTRIBUTING.md) · [Agent guide](AGENTS.md) · [TypeSafe API documentation](https://docs.typesafe.ai/api)
7+
[Developer guide](docs/discovery/README.md) · [Contributing](CONTRIBUTING.md) · [Agent instructions](AGENTS.md) · [Jev Labs](docs/jev-labs.md) · [Official API documentation](https://docs.typesafe.ai/introduction/quickstart)
88

9-
## What this repository provides
9+
![TypeSafe UI: an unofficial community component workspace](docs/discovery/assets/social-preview.svg)
1010

11-
A Turborepo + pnpm workspace with a Next.js component browser, source previews, install/import examples, and an interactive Lab. The UI uses the shadcn `base-nova` style, Base UI primitives, Tailwind v4, and RTL-aware components.
11+
## What is here
1212

13-
The site pairs an original optical-glass photographic introduction with an OpenCoven-inspired workspace: a sticky topbar, grouped component rail, per-component Preview/Source and Install/Import tabs, and an “On this page” outline. Its TypeSafe-inspired theme uses pink primary, teal live-state accents, dark mode by default, IBM Plex typography, a dot-grid background, and softly illuminated preview surfaces.
13+
A Turborepo and pnpm workspace with a Next.js component browser, source previews, install/import examples, and an interactive Lab. It uses the shadcn `base-nova` style, Base UI primitives, Tailwind v4, and RTL-aware components. The interface supports light/dark themes and TypeSafe-inspired pink/teal styling.
1414

15-
`@workspace/ui` is a **private workspace package**, not a published npm package. The imports below work inside this monorepo. For another application, deliberately port the components, styles, dependencies, and aliases you need; do not assume `npm install typesafe-ui` or a hosted registry exists. A visual “live” state is not proof of a real Jev API call.
15+
`@workspace/ui` is a **private workspace package**, not a published npm package. Imports work inside this monorepo. For another application, deliberately port the components, styles, dependencies, and aliases you need; do not assume `npm install typesafe-ui` or a hosted registry exists.
1616

17-
## Getting started
17+
The Jev Labs guide describes the upstream catalog examples, workspace scenarios, and interface patterns. Outputs in these previews are local fixtures. A visual live-state indicator is not proof of a Jev API call.
1818

19-
Use the pnpm version pinned in [package.json](package.json), currently `10.33.4`. The root manifest declares Node.js `>=20`; use a Node version supported by the checked-in Next.js dependency as well. Node.js 22+ is a practical development baseline.
19+
## Run locally
20+
21+
Use the exact pnpm version declared in [package.json](package.json). The manifest declares Node.js `>=20`; use a version supported by the checked-in Next.js dependency as well. Node.js 22+ is a practical development baseline.
2022

2123
```sh
2224
git clone https://github.com/TypeSafeAI/typesafe-ui.git
2325
cd typesafe-ui
24-
# Install/activate the pnpm version declared in package.json.
25-
# Where Corepack is installed, `corepack enable` enables its package-manager shims.
26+
# Activate the pnpm version declared in package.json.
27+
# Corepack can enable package-manager shims where it is installed.
2628
pnpm install --frozen-lockfile
2729
pnpm dev
2830
```
2931

30-
The [Jev Labs guide](docs/jev-labs.md) covers 169 local examples: all 110 upstream catalog examples, 56 workspace scenarios, and three interface patterns. Labs share the library’s sidebar, source inspection, and installation/import workflow. All outputs are explicitly local fixtures.
31-
32-
Open the address printed by the development server, normally `http://localhost:3000`. The library is at `/`, and interactive scenes are at `/lab`. Press `d` to toggle dark mode and `⌘K` to search components.
32+
Open the address printed by the development server, normally `http://localhost:3000`. The library is at `/` and the interactive scenes are at `/lab`. Press `d` to toggle dark mode and `Cmd+K` to search components. No provider credentials are needed to browse local fixtures.
3333

3434
| Command | Purpose |
3535
| --- | --- |
36-
| `pnpm dev` | Run the web application through Turborepo. |
37-
| `pnpm build` | Build the workspace. |
38-
| `pnpm lint` | Run workspace lint tasks. |
39-
| `pnpm typecheck` | Run workspace TypeScript checks. |
40-
| `pnpm test:e2e` | Run Playwright browser checks for the catalog, Lab, navigation, themes, and motion. |
41-
| `pnpm format` | Format source files; this writes changes. |
36+
| `pnpm dev` | Run the web application through Turborepo |
37+
| `pnpm build` | Build the workspace |
38+
| `pnpm lint` | Run workspace lint tasks |
39+
| `pnpm typecheck` | Run workspace TypeScript checks |
40+
| `pnpm test:e2e` | Run Playwright browser checks |
41+
| `node --test scripts/social-metadata.test.mjs` | Check sharing-source invariants without installing dependencies |
42+
| `pnpm format` | Format source files; this writes changes |
4243

43-
There is no root unit-test script. `pnpm test:e2e` runs the checked-in Playwright suite (local Google Chrome; bundled Chromium in CI). Browser checks complement visual and keyboard inspection; they do not prove accessibility.
44+
There is no root `pnpm test` script. The E2E suite uses local Google Chrome, or bundled Chromium in CI. Source checks do not prove that a deployed image loads, and browser automation does not establish complete accessibility.
4445

45-
## Layout
46+
## Project map
4647

4748
```text
4849
apps/web/
49-
app/ Next.js routes, layout, fonts, and metadata
50-
components/ Site shell, component cards, demos, and Lab scenes
51-
lib/ Site config, component registry, source loader, and shiki
50+
app/ routes, layout, fonts, and social metadata
51+
components/ shell, component cards, previews, and Lab scenes
52+
lib/ site configuration, registries, source loader, and shiki
5253
packages/
53-
ui/ @workspace/ui: components, hooks, utilities, and styles
54-
eslint-config/ Shared lint configuration
55-
typescript-config/ Shared TypeScript configuration
54+
ui/ @workspace/ui components, hooks, utilities, and styles
55+
eslint-config/ shared lint configuration
56+
typescript-config/ shared TypeScript configuration
5657
```
5758

58-
## Adding a component
59+
## Add a component or lab
5960

60-
1. Add a component against the web app. The existing shadcn configuration places reusable components in `packages/ui/src/components`.
61+
1. Add a component against the web app; the shadcn configuration places reusable components in `packages/ui/src/components`.
6162

6263
```sh
6364
pnpm dlx shadcn@latest add popover -c apps/web
6465
```
6566

66-
This is a generator operation that can change source and dependencies. Review its diff and the lockfile rather than treating it as a read-only command.
67+
This is a generator operation that can modify source and dependencies. Review its complete diff and lockfile changes; it is not a read-only command.
6768

68-
2. Register the component in `apps/web/lib/registry.ts`: id, title, group, description, exports, and supported states.
69-
3. Add a demo using the same id in `apps/web/components/demos.tsx`.
70-
4. Verify its preview, source, import example, keyboard behavior, themes, narrow layout, and RTL behavior.
69+
2. Register the component in `apps/web/lib/registry.ts` with its ID, group, description, exports, and supported states.
70+
3. Add its demo using the same ID in `apps/web/components/demos.tsx`.
71+
4. Verify preview, displayed source, imports, keyboard behavior, themes, narrow layout, and RTL.
7172

72-
The library reads component source from disk at build time and highlights it with shiki. Keep registry ids, exported paths, source paths, and demos aligned.
73+
For a Jev Lab, follow [the Lab guide](docs/jev-labs.md) and preserve upstream IDs, declared A/B differences, local-fixture labels, and attribution. The library reads component source at build time and highlights it with shiki; keep registry IDs, source paths, exports, and demos aligned.
7374

74-
## Using components
75+
## Use components
7576

7677
```tsx
7778
import { Button } from "@workspace/ui/components/button"
7879
```
7980

80-
Base UI triggers compose through the `render` prop rather than Radix-style `asChild`. A `Button` rendered as a link needs `nativeButton={false}`. Keep provider credentials and application-specific network clients out of reusable client components.
81+
Base UI triggers compose through `render`, rather than Radix-style `asChild`. A Button rendered as a link needs `nativeButton={false}`. Keep provider credentials and application-specific network clients out of reusable client components.
82+
83+
## Themes and RTL
84+
85+
Tokens live in `packages/ui/src/styles/globals.css`: light values in `:root` and dark values in `.dark`. TypeSafe-oriented tokens include `--teal`, `--success`, `--warning`, and `--dot`. Fonts are wired through `next/font` in `apps/web/app/layout.tsx` and exposed as `--font-sans` and `--font-mono`.
86+
87+
Site identity, links, navigation, language, and direction live in `apps/web/lib/site.ts`. The shadcn configuration has `rtl: true`. Set `dir` and `lang` deliberately for a locale, preserve DirectionProvider, and prefer logical CSS properties.
8188

82-
## Theming and RTL
89+
## Sharing and screenshots
8390

84-
Tokens live in `packages/ui/src/styles/globals.css`: light values in `:root`, dark values in `.dark`. TypeSafe-oriented tokens include `--teal`, `--success`, `--warning`, and `--dot`. Fonts are wired through `next/font` in `apps/web/app/layout.tsx` and exposed as `--font-sans` and `--font-mono`.
91+
`apps/web/app/opengraph-image.tsx` renders a public editorial PNG. Twitter metadata uses the same route. Verify the rendered tags and image response after building and deploying; do not claim production publication from a source diff alone. The SVG shown above is editable artwork, not an application screenshot.
8592

86-
Site name, tagline, links, navigation, language, and direction live in `apps/web/lib/site.ts`. The shadcn configuration has `"rtl": true`. Set `dir` to `"rtl"` and `lang` to the intended locale to update the root layout and `DirectionProvider`. Prefer logical CSS properties so components work in both directions.
93+
The [developer guide](docs/discovery/README.md) links publishing and screenshot protocols. Use synthetic local previews, keep fixture labels visible, and record the source revision, viewport, theme, direction, and capture environment. Review media for private data. `repository-metadata.json` documents proposed About text/topics; it does not apply GitHub settings.
8794

8895
## Related community projects
8996

9097
| Repository | Role |
9198
| --- | --- |
92-
| [typesafe-ai-playground](https://github.com/BunsDev/typesafe-ai-playground) | Interactive Jev experiments and integration demos. |
93-
| [clarity-judge](https://github.com/BunsDev/clarity-judge) | Separate, named writing-quality checks. |
94-
| [typesafe-router](https://github.com/BunsDev/typesafe-router) | Closed-set tool and model routing, separate from execution. |
95-
| [typesafe-ui](https://github.com/TypeSafeAI/typesafe-ui) | Reusable components and interface patterns. |
99+
| [typesafe-playground](https://github.com/TypeSafeAI/typesafe-playground) | Interactive Jev experiments and integration demos |
100+
| [clarity-judge](https://github.com/TypeSafeAI/clarity-judge) | Separate named writing-quality checks |
101+
| [typesafe-router](https://github.com/TypeSafeAI/typesafe-router) | Closed-set selection, separate from authorization and execution |
102+
| [jev-harness](https://github.com/TypeSafeAI/jev-harness) | Proposal-review evidence and synthetic fixtures |
96103

97-
These are separate repositories, not an automatically integrated or officially supported product suite. The proposed GitHub description and discovery topics are recorded in [repository-metadata.json](repository-metadata.json); that file does not change GitHub settings automatically.
104+
These are independent community projects, not an automatically integrated or officially supported suite. Preserve shadcn/ui and Base UI attribution, TypeSafe-inspired branding, the OpenCoven layout inspiration, and existing source/license notices. Review the applicable licenses before reusing code; this change does not alter licensing.

‎apps/web/app/layout.tsx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ export const metadata: Metadata = {
3939
},
4040
twitter: {
4141
card: "summary_large_image",
42+
images: [{ url: "/opengraph-image", alt: "TypeSafe UI — unofficial community component workspace" }],
4243
},
4344
}
4445

‎apps/web/app/opengraph-image.tsx‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
import { ImageResponse } from "next/og"
2+
import { site } from "@/lib/site"
3+
4+
export const alt = "TypeSafe UI — unofficial community component workspace"
5+
export const size = { width: 1200, height: 630 }
6+
export const contentType = "image/png"
7+
8+
// Public editorial artwork only: no request data, provider calls, or credentials.
9+
export default function Image() {
10+
return new ImageResponse(
11+
<div style={{ display: "flex", flexDirection: "column", width: "100%", height: "100%", padding: "56px 64px", background: "#080e16", color: "#f5f7fb", borderTop: "8px solid #f0a5ca", fontFamily: "sans-serif" }}>
12+
<div style={{ display: "flex", fontSize: 22, letterSpacing: 2, color: "#a3e7d7" }}>TYPESAFEAI / UNOFFICIAL COMMUNITY</div>
13+
<div style={{ display: "flex", marginTop: 48, fontSize: 72, fontWeight: 700 }}>{site.name}</div>
14+
<div style={{ display: "flex", marginTop: 18, fontSize: 34, color: "#f0a5ca" }}>{site.tagline}</div>
15+
<div style={{ display: "flex", marginTop: 28, fontSize: 25, color: "#acb8c9" }}>React components · Source previews · Interface patterns</div>
16+
<div style={{ display: "flex", gap: 20, marginTop: 42 }}>
17+
{["Preview", "Inspect source", "Reuse deliberately"].map((label) => (
18+
<div key={label} style={{ display: "flex", flex: 1, padding: "22px 24px", border: "1px solid #34404f", borderRadius: 12, background: "#101924", fontSize: 25 }}>{label}</div>
19+
))}
20+
</div>
21+
<div style={{ display: "flex", justifyContent: "space-between", marginTop: "auto", paddingTop: 24, borderTop: "1px solid #34404f", fontSize: 20 }}>
22+
<span>TypeSafeAI / typesafe-ui</span>
23+
<span style={{ color: "#a3e7d7" }}>Community-built. Not official.</span>
24+
</div>
25+
</div>,
26+
size
27+
)
28+
}

0 commit comments

Comments
 (0)