@pontive/pontkit-core 1.0.0

package/README.md

@@ -0,0 +1,142 @@
+# @pontive/pontkit-core
+
+The PontKit element bundle: 270 Lit custom elements that render Pontive's
+authentication, profile and organization surfaces, plus the design tokens that
+style them.
+
+This is the runtime. Framework bindings (`@pontive/pontkit-react`, `-vue`, …)
+are thin wrappers over these tags — they contain no elements of their own.
+Nothing here is React-aware: no React in the source, and no framework peer
+dependencies, so installing this does not drag one in.
+
+```html
+<pont-provider>
+  <pont-signin></pont-signin>
+</pont-provider>
+```
+
+```js
+// `env` is a property, not an attribute — it is an object.
+document.querySelector("pont-provider").env = {
+  domain: "tenant.idp.us.pontive.app",  // or "/__auth" when proxied
+  appId: "app_...",
+  projectId: "proj_...",
+  apiBaseUrl: "https://api...",
+};
+```
+
+`<pont-provider>` configures the auth engine and provides the locale, branding
+and auth-state contexts every other element consumes. Widgets outside it do not
+work.
+
+## What is in it
+
+| Layer | Count | What it is |
+|---|---|---|
+| **Widgets** | 64 | The composed surfaces: `pont-signin`, `pont-signup`, `pont-provider`, `pont-account-settings`, `pont-member-management`, … |
+| **Primitives** | 206 | The internal component library the widgets are built from — buttons, inputs, popovers, tables. Absorbed from the Revotech UI kit, which this package used to depend on. |
+| **Catalog** | 29 | The subset a brand author may place in a widget. See below. |
+
+Everything shares the `pont-` prefix. Everything renders into **light DOM**
+(`createRenderRoot() { return this }`), which is why the Tailwind utilities are
+prefixed too — those class names land in the host application's stylesheet.
+
+## How it is delivered
+
+Not bundled by the app. `@pontive/pontkit-loader` fetches this package at
+runtime from a URL the platform decides:
+
+1. The project's auth server names an **exact** release and its SRI hashes
+   (`GET /auth/v1/runtime-config`). This is how a canary or a hot fix reaches a
+   deployed app with nothing rebuilt.
+2. Failing that, the exact release the binding was built and tested against.
+
+Never a range and never `latest` — an exact version is immutable on the CDN,
+cacheable forever, and the only form that admits an integrity hash. Which
+release a project serves is administered in `branding-svc`
+(`deployment_core_elements`, with a per-project override for canaries).
+
+Install it directly only to generate bindings or to run the catalog checks; a
+front end takes `@pontive/pontkit-react` and lets the loader do the rest.
+
+## The catalog
+
+`catalog.json` is the **cross-service contract**. It names the 29 elements a
+brand author may place, with their attributes, defaults and constraints:
+
+`pont-alert` `pont-confirm-field` `pont-container` `pont-countdown`
+`pont-divider` `pont-edit-identifier` `pont-email-field` `pont-form` `pont-gap`
+`pont-header` `pont-identifier-field` `pont-link` `pont-logo` `pont-name-field`
+`pont-otp` `pont-otp-resend` `pont-passkey-button` `pont-password-field`
+`pont-phone-field` `pont-provider-button` `pont-provider-field` `pont-qr-code`
+`pont-recovery-codes` `pont-secret` `pont-submit-button` `pont-subtitle`
+`pont-title` `pont-username-field` `pont-watermark`
+
+`branding-svc` curates against it and rejects markup that uses anything else;
+`identity-svc`'s flow engine keys off these tags and attribute names. The other
+241 elements are internal — a primitive in brand markup is removed, not
+rendered. Changing a tag or an attribute key here is a cross-service change, not
+a rename. `npm run check:catalog` fails when the catalog and the elements
+disagree about a default.
+
+## Design tokens
+
+Three tiers, under `src/tokens`, compiled into `dist/styles.css`:
+
+| Tier | Shape | Holds |
+|---|---|---|
+| Reference | `--pont-ref-color-brand-600` | Raw scales. Bare HSL triples. |
+| Semantic | `--pont-sem-color-bg-surface` | Roles. Also triples. |
+| Component | `--pont-card-color-bg` | What an element reads at its use site. **Complete** colors, wrapped in `hsl()`. |
+
+The distinction is load-bearing: a bare triple in the component tier silently
+fails to parse. `branding-svc` compiles a brand's overrides into exactly these
+names server-side and stores the result, so a token rename is a coordinated
+change across this package, `branding-svc` and the dashboard's branding panel —
+never a local edit.
+
+## Consuming it
+
+```ts
+import { useAuthProvider } from "@pontive/pontkit-core";
+import "@pontive/pontkit-core/dist/styles.css";
+
+const auth = useAuthProvider();
+await auth.whenConfigured();
+```
+
+`useAuthProvider()` hands back the `Auth` singleton from
+[`@pontive/oidc-client`](https://github.com/revotech-group/pontive-oidc-client),
+which holds the sessions, login flows and WebAuthn. `<pont-provider>` calls
+`configure()` on it, so a widget mounted inside the provider needs no setup of
+its own. That package is browser-only and has no UI; depend on it directly when
+you are building your own.
+
+Importing this package **registers all 270 elements**. It is
+`sideEffects: true` on purpose: `@customElement` registers on import, so a
+bundler that treated the module as pure would drop the entire element registry.
+
+## Development
+
+```sh
+npm install
+npm run dev              # Vite playground
+npm run storybook        # 444 stories and docs pages
+npm run build            # dist/index.mjs + dist/index.js + dist/styles.css
+npm test                 # vitest
+npm run check:catalog    # catalog vs. element defaults
+npm run check:names      # fails on any surviving pre-PontKit name
+```
+
+`check:names` and `check:catalog` both run on `prepublishOnly`. The first exists
+because a renamed tag breaks loudly while a missed Tailwind class is invisible —
+it is simply never generated, and the element quietly loses its styling.
+
+## Related
+
+| | |
+|---|---|
+| [`pontive-oidc-client`](https://github.com/revotech-group/pontive-oidc-client) | `@pontive/oidc-client` — the auth engine this wraps |
+| [`pontkit`](https://github.com/revotech-group/pontkit) | The loader and the framework bindings |
+| `branding-svc` | Curates the catalog, compiles brand tokens, decides which release a project serves |
+| `identity-svc` | Serves the flow definitions these elements render |