@danxbot/plugin-sdk 0.0.0-stage → 0.1.2

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# @danxbot/plugin-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Build a 50 Arms **card-type plugin**: a small React bundle that gives a card type its own card view (`CardView`) and/or card-list view (`CardListView`), loaded into 50 Arms' own page with `import()`.
+
+A plugin does not bundle React, `@danxbot/ui` or the card features. The app serves them under fixed import specifiers through an import map, so a plugin shares the app's single React and renders the app's own components:
+
+| Specifier | What it is |
+|---|---|
+| `react`, `react/jsx-runtime`, `react-dom` | The app's React |
+| `@danxbot/ui` | The app's design system |
+| `@danxbot/card-kit@1` | The card features: data hooks, card regions (`StandardCardPage`, `EditableTitle`, `ChecklistsSection`, ...), `CardFace`, `CardBoard` |
+
+The live list and each library's major version is `GET /api/plugin-runtime`.
+
+## Set up a plugin
+
+`package.json`: depend on `@danxbot/plugin-sdk` and install its peers: `vite`, `react`, `@types/react`, `@danxbot/ui` and `react-router` (types only: the app serves the real ones; the kit's declarations import them).
+
+`vite.config.ts`:
+
+```ts
+import { defineConfig } from "vite";
+import { danxPlugin } from "@danxbot/plugin-sdk/vite";
+
+export default defineConfig({ plugins: [danxPlugin()] });
+```
+
+`tsconfig.json`: add `"types": ["@danxbot/plugin-sdk/card-kit"]`: the kit's declarations. They are self-contained (they import only `react`, `@danxbot/ui` and `react-router`) and the specifier is not a package, so TypeScript reads them as ambient types.
+
+`src/index.tsx` exports `CardView` and/or `CardListView`:
+
+```tsx
+import { StandardCardPage, type CardViewProps } from "@danxbot/card-kit@1";
+
+export function CardView({ card, mutation }: CardViewProps) {
+  return <StandardCardPage card={card} mutation={mutation} />;
+}
+```
+
+`vite build` writes the plugin to `dist/`: `index.js` (the entry), `chunks/` for code splitting, `index.css`, source maps, and `danx-plugin.json`, the manifest listing every file with its size and sha256 and the runtime majors the plugin was built against.
+
+The build refuses to bundle a copy of React, React DOM, `@danxbot/ui` or `react-router`: import only the specifiers above. For routing, use the kit's `Link` and `useNavigate`; `StandardCardPage` reads the plan the page was opened from out of the URL, so a view that wraps it passes only `{card, mutation}`.
+
+## The card kit is a contract
+
+A runtime export of `@danxbot/card-kit@1`, and its parameters, is never removed or changed in place; the keys of the exported data types follow the Versioning section below. A breaking change is `@danxbot/card-kit@2`, served beside `@1` until no approved plugin revision needs it. A plugin's manifest records the majors it was built against, and the app refuses to run a revision built for a major it no longer serves.
+
+## `danx-plugin publish`
+
+Not available yet: it refuses with an error until the plugin upload route ships in the next release of this SDK.
+
+## Versioning
+
+The SDK stays 0.x until the shapes behind the card kit's data types settle: phase 1 of DX-4679 (card types as rows) changes `IssueViewV2.type`, and DX-5164 (designs on any card) changes the design fields. Until then the declarations may change between 0.x releases; the kit's runtime exports follow the `@danxbot/card-kit@1` rule above.