@zerops/web-components 0.0.1

package/README.md

@@ -0,0 +1,117 @@
+# @zerops/web-components
+
+Zerops UI as framework-agnostic web components. Each element is a self-registering ES module entry — import it for its side effect and use the tag anywhere: plain HTML, React, Vue, Svelte, anything that renders DOM.
+
+Angular is fully bundled inside (zoneless, shared across all elements on the page); the package has **no peer dependencies**.
+
+## Setup
+
+Every page using the components needs the stylesheet and the fonts once:
+
+```html
+<link href="https://fonts.googleapis.com/css2?family=Geologica:wght@100..900&display=swap" rel="stylesheet">
+<link href="https://fonts.googleapis.com/icon?family=Material+Icons+Outlined" rel="stylesheet">
+```
+
+```js
+import '@zerops/web-components/style.css';
+```
+
+## `<zerops-recipe-card>`
+
+```js
+import '@zerops/web-components/recipe-card';
+```
+
+### Self-fetching mode
+
+The element fetches the recipe from the public Zerops API (CORS-open) at load:
+
+```html
+<zerops-recipe-card slug="nestjs-minimal"></zerops-recipe-card>
+```
+
+### Captured-data mode — no API call
+
+Ship the recipe snapshot with your page and the card renders instantly:
+
+```js
+import showcase from '@zerops/web-components/recipes/zerops-showcase.json';
+
+const card = document.querySelector('zerops-recipe-card');
+await customElements.whenDefined('zerops-recipe-card');
+card.recipeData = showcase;
+```
+
+### React
+
+```tsx
+import { useEffect, useRef } from 'react';
+import '@zerops/web-components/recipe-card';
+import '@zerops/web-components/style.css';
+import type { ZeropsRecipeCardElement } from '@zerops/web-components/recipe-card';
+
+export function ZeropsRecipeCard({ slug, recipeData, onDeployed }: {
+  slug?: string;
+  recipeData?: object;
+  onDeployed?: (appUrl: string) => void;
+}) {
+  const ref = useRef<ZeropsRecipeCardElement>(null);
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    const handler = (e: CustomEvent<string>) => onDeployed?.(e.detail);
+    el.addEventListener('deployed', handler);
+    return () => el.removeEventListener('deployed', handler);
+  }, [onDeployed]);
+
+  useEffect(() => {
+    if (!recipeData) return;
+    customElements.whenDefined('zerops-recipe-card').then(() => {
+      if (ref.current) ref.current.recipeData = recipeData;
+    });
+  }, [recipeData]);
+
+  return <zerops-recipe-card ref={ref} slug={slug} />;
+}
+```
+
+With React 19 you can also set `recipeData` directly as a JSX prop (React assigns it as a DOM property); the wrapper above works on 18 and 19.
+
+For TypeScript JSX, augment the intrinsic elements once:
+
+```tsx
+declare module 'react' {
+  namespace JSX {
+    interface IntrinsicElements {
+      'zerops-recipe-card': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
+        slug?: string;
+        'api-base'?: string;
+        'app-url'?: string;
+      };
+    }
+  }
+}
+```
+
+### Attributes / properties
+
+| Name | Attribute | Default | |
+|------|-----------|---------|-|
+| `slug` | `slug` | — | Catalog slug to self-fetch |
+| `recipeData` | `recipe-data` (JSON string) | — | Captured recipe; wins over `slug` |
+| `apiBase` | `api-base` | `https://api.zerops.io` | Public API origin |
+| `appUrl` | `app-url` | `https://app.zerops.io` | Detail/deploy link origin |
+
+### Events (CustomEvents on the element)
+
+| Event | `detail` | |
+|-------|----------|-|
+| `deployed` | `string` | Deploy clicked; the app URL that was opened |
+| `detailOpened` | — | A detail/title link was clicked |
+
+## Known caveats
+
+- The stylesheet includes a CSS-layered normalize that can nudge host-page base styles.
+- Recipe snapshots under `recipes/` are frozen at package publish time; use `slug` mode for always-current data.