@adia-ai/adia-ui-factory 0.2.3 → 0.8.0

package/skills/adia-ui-kit/references/rendering-model.md

@@ -1,431 +0,0 @@
-# §Rendering Model — SPA, SSR, or static?
-
-> **Loading note.** Reference bundle extracted from `SKILL.md` per the
-> §LoadingProtocol inversion contract (v2.20.1+). Load via
-> `skill_view(name='adia-ui-kit', file_path='references/rendering-model.md')`
-> when you need to wire AdiaUI into a framework with a specific rendering
-> model — Next.js / Nuxt / SvelteKit / Astro / plain SPA / static. Skip
-> if you're in a vanilla Vite SPA (the §Setup defaults cover that case).
-
-Determine this **before writing any markup or imports.** The rendering
-model changes which patterns from §Flows are safe to use directly and
-which need adaptation.
-
-### Decision tree
-
-```
-Does your project run a server that renders HTML per-request?
-  YES → SSR (Next.js, Nuxt, SvelteKit, Remix, Astro SSR)
-        → See "SSR" column below
-  NO  →
-    Does it build to static HTML files at deploy time?
-      YES → Static site (Astro SSG, plain HTML, Vite static build)
-            → Same as SPA; no adaptation needed
-      NO  →
-        SPA (Vite + vanilla, React SPA, Vue SPA, Create React App)
-        → See "SPA" column below
-```
-
-### Compatibility matrix
-
-| Feature | SPA / Static | SSR (Next/Nuxt/SvelteKit) |
-|---|---|---|
-| `import '@adia-ai/web-components'` | ✓ top-level | ✗ server throws `HTMLElement is not defined` — use dynamic import or client directive |
-| CSS imports | ✓ top-level | ✓ top-level (CSS has no browser APIs) |
-| `data-stream-*` attributes | ✓ | ✓ (guarded with `typeof document !== 'undefined'` internally) |
-| `<script type="module">` for router/table/chart wiring | ✓ | ✗ DOM not available at server render — wrap in `onMounted` / `useEffect` / `client:only` |
-| Form participation (`ElementInternals`) | ✓ | Works after hydration; server HTML has no form state |
-| `customElements.whenDefined()` | ✓ | Only safe inside client-side lifecycle hooks |
-| **Routing — `<router-ui>`** | ✓ canonical SPA pattern | ✗ **DO NOT USE** — server framework owns routing. See **Routing ownership** below. |
-
-### Routing ownership — when to use `<router-ui>` vs the server framework
-
-`<router-ui>` is a client-side SPA router. It listens for `popstate`,
-intercepts `<a>` clicks, calls `history.pushState`, and renders the
-matched route's content fragment into its own subtree. It is the
-**canonical AdiaUI routing primitive for SPA + static contexts** and
-the default `<router-ui></router-ui>` slot in the admin-shell anatomy
-assumes you'll wire routes to it.
-
-**In SSR contexts this is wrong.** The server framework already owns
-routing: it parses the URL, runs route handlers, renders the page on
-the server, and ships HTML. Page navigations are full HTTP requests
-(or framework-managed pushState via `<Link>` / `<NuxtLink>` / etc.).
-Using `<router-ui>` alongside the server's router creates two
-competing route owners — clicks get intercepted twice, the URL
-desynchronizes from the rendered content, and SSR's "URL is the
-source of truth for the server-rendered HTML" contract breaks.
-
-**Rule:** there is exactly ONE route owner per app. Pick the right one
-for your rendering model and don't introduce the other.
-
-| Rendering model | Route owner | What replaces `<router-ui>` |
-|---|---|---|
-| SPA (Vite + vanilla, React SPA, Vue SPA, CRA, Solid, …) | `<router-ui>` | — (this IS the canonical primitive) |
-| Static (Astro SSG, plain HTML, Vite static build, GH Pages) | `<router-ui>` OR none (multi-page static) | If multi-page, just use `<a href="…">` — the browser fetches the next page. `<router-ui>` only needed if you want SPA-style fragment swapping over a static build. |
-| **Next.js App Router** | Next.js | `<Link>` from `next/link` + `app/[…]/page.tsx` filesystem routes. `usePathname()` / `useSearchParams()` for read access. |
-| **Next.js Pages Router** | Next.js | `<Link>` from `next/link` + `pages/[…].tsx` filesystem routes. `useRouter()` for read+write access. |
-| **Nuxt 3** | Nuxt / Vue Router | `<NuxtLink>` + `pages/[…].vue` filesystem routes. `useRoute()` / `useRouter()`. |
-| **SvelteKit** | SvelteKit | `<a href="…">` (intercepted by the SvelteKit client) + `src/routes/[…]/+page.svelte` filesystem routes. `$page` store. |
-| **Remix / React Router** | Remix / React Router | `<Link>` + `app/routes/[…].tsx` filesystem routes. `useNavigate()` / `useLocation()`. |
-| **Astro (SSR mode)** | Astro | `<a href="…">` (full reload) OR opt-in `<ViewTransitions />` for SPA-style swaps. `Astro.url` / `Astro.params` server-side. |
-| **Rails + Turbo** | Rails | `link_to` + `config/routes.rb`. Turbo Drive intercepts and swaps the body. Don't add `<router-ui>` — Turbo is already doing it. |
-| **Django + HTMX** | Django | `{% url %}` + `urls.py`. HTMX `hx-get` for partial swaps. `<router-ui>` would fight HTMX. |
-| **Phoenix LiveView** | Phoenix | `<.link>` + `live "/path"` routes. LiveView owns navigation + DOM patching end-to-end. |
-
-**Concrete substitution — the admin-shell example in §Patterns.** The
-canonical SPA flow is:
-
-```html
-<admin-shell>
-  <admin-sidebar slot="leading">…</admin-sidebar>
-  <admin-content>
-    <admin-topbar slot="header">…</admin-topbar>
-    <admin-scroll>
-      <!-- SPA route owner: your framework's route outlet element goes here
-           (vue-router-view, react Outlet, lit-router-outlet, slot, etc.) -->
-    </admin-scroll>
-  </admin-content>
-</admin-shell>
-<script type="module">
-  // Wire your router of choice — example below uses a generic router instance:
-  router.outlet = document.querySelector('admin-shell admin-scroll');
-  router.routes = [/* … */];
-</script>
-```
-
-In **Next.js App Router**, the same anatomy becomes:
-
-```tsx
-// app/layout.tsx — the shell renders once, persists across navigations
-'use client';
-export default function Layout({ children }) {
-  return (
-    <admin-shell>
-      <admin-sidebar slot="leading">…</admin-sidebar>
-      <admin-content>
-        <admin-topbar slot="header">…</admin-topbar>
-        <admin-scroll>
-          {children}   {/* ← Next's route content fills this slot */}
-        </admin-scroll>
-      </admin-content>
-    </admin-shell>
-  );
-}
-// app/claims/page.tsx → renders into {children}
-// app/claims/[id]/page.tsx → renders into {children}
-```
-
-No `<router-ui>`. No `<script>` for route registration. Next's
-filesystem routing IS the routing.
-
-**In SvelteKit** the parallel is `src/routes/+layout.svelte` holding
-the admin-shell + `<slot />` where `<router-ui>` would have been.
-
-**In Astro** (without `<ViewTransitions />`), every navigation is a
-full reload — the shell re-renders per page, so just write each
-page's HTML and put the shell in a shared layout component. With
-`<ViewTransitions />` enabled, Astro does SPA-style swaps but it's
-still Astro that owns routing, not `<router-ui>`.
-
-**Cross-cutting state in SSR (since the shell re-mounts per page):**
-keep the sidebar collapsed/open state, the active nav highlight, and
-any optimistic UI in `cookies` / `localStorage` / a server session —
-not in client-only signals scoped to a `<router-ui>` lifetime. The
-admin-shell + admin-sidebar primitives read these stores happily; see
-the framework's docs (`cookies()` in Next, `useCookie()` in Nuxt,
-`event.cookies` in SvelteKit) for the canonical write path.
-
-**How to discover which mode you're in (cold-start checklist):**
-
-1. Look at the project root. `next.config.{js,mjs,ts}` → Next.js.
-   `nuxt.config.ts` → Nuxt. `svelte.config.js` → SvelteKit.
-   `astro.config.mjs` → Astro. `app.config.ts` or `app.vue` → Vue/Nuxt.
-   `config/routes.rb` → Rails. `manage.py` → Django. `mix.exs` +
-   `lib/*_web/router.ex` → Phoenix.
-2. If NONE of those exist and the entry point is a single `index.html`
-   with `<script type="module" src="./main.{js,ts}">` → SPA. Use
-   `<router-ui>`.
-3. If `vite build` produces multiple `.html` files (Vite multi-page
-   mode) → static; `<router-ui>` is optional.
-4. **When in doubt, grep the project root:** `grep -rE
-   "(next|nuxt|sveltekit|astro|remix)" package.json` reveals the
-   framework. If the project has its own router primitive, USE IT.
-
-**Don't get caught in the middle.** Re-confirm the routing model
-BEFORE you wire any navigation — anchors, breadcrumbs, sidebar nav
-items, active-state highlighting all hook into the route owner. If
-you start the session assuming SPA + `<router-ui>` and the project
-turns out to be Next App Router, every nav primitive needs rework.
-The cost of a 30-second `ls + grep` at the start is much smaller than
-the cost of mid-flight refactoring.
-
-### SPA / static (Vite, plain HTML)
-
-All patterns in §Flows work as written. Use them verbatim.
-
-```js
-// main.js — top-level, runs once at page load
-import '@adia-ai/web-components/css';
-import '@adia-ai/web-components';
-import '@adia-ai/web-modules/shell';         // per-cluster — the full '@adia-ai/web-modules' barrel ships broken absolute paths at v0.6.7
-import '@adia-ai/web-modules/shell/admin-shell.css';  // REQUIRED — see §CSSPolicy
-import { installIconLoadersForRegistered } from '@adia-ai/web-components/core/icons';
-installIconLoadersForRegistered(import.meta.glob(
-  '../node_modules/@phosphor-icons/core/assets/regular/*.svg',
-  { query: '?raw', import: 'default', eager: true }
-));
-```
-
-### SSR — Next.js (App Router)
-
-```tsx
-// components/AdiaProvider.tsx  ← client boundary
-'use client';
-
-import { useEffect } from 'react';
-
-export function AdiaProvider({ children }: { children: React.ReactNode }) {
-  useEffect(() => {
-    // Dynamic import: runs only in browser, never on server
-    import('@adia-ai/web-components').then(() =>
-      import('@adia-ai/web-modules/shell')   // per-cluster, NOT the full barrel
-    ).then(async () => {
-      // CSS — REQUIRED (see §CSSPolicy)
-      await import('@adia-ai/web-components/css');
-      await import('@adia-ai/web-modules/shell/admin-shell.css');
-      const { installIconLoadersForRegistered } =
-        await import('@adia-ai/web-components/core/icons');
-      const modules = await import(
-        /* @vite-ignore */ '../node_modules/@phosphor-icons/core/assets/regular/*.svg'
-      );
-      installIconLoadersForRegistered(modules);
-    });
-  }, []);
-
-  return <>{children}</>;
-}
-
-// Wrap your layout or root component:
-// app/layout.tsx
-// <AdiaProvider><body>{children}</body></AdiaProvider>
-```
-
-All `<script type="module">` wiring blocks from §Flows (router routes,
-table.columns, chart.data) must move inside `useEffect`:
-
-```tsx
-'use client';
-import { useEffect, useRef } from 'react';
-
-export function UsersTable({ data }) {
-  const tableRef = useRef(null);
-  const toolbarRef = useRef(null);
-
-  useEffect(() => {
-    if (!tableRef.current || !toolbarRef.current) return;
-    toolbarRef.current.table = tableRef.current;
-    tableRef.current.columns = [
-      { key: 'name',   label: 'Name',   type: 'avatar' },
-      { key: 'status', label: 'Status', type: 'badge',
-        meta: { variants: { Active: 'success', Inactive: 'danger' } } },
-    ];
-    tableRef.current.data = data;
-  }, [data]);
-
-  return (
-    <card-ui>
-      <header><span slot="heading">Users</span></header>
-      <section style={{ padding: 0 }}>
-        <table-toolbar-ui ref={toolbarRef} />
-        <table-ui ref={tableRef} sortable striped />
-      </section>
-    </card-ui>
-  );
-}
-```
-
-> **TypeScript: custom elements in JSX.** Add a declaration to stop
-> "intrinsic element" errors:
-> ```ts
-> // types/adia-ui.d.ts
-> declare namespace JSX {
->   interface IntrinsicElements {
->     [tag: string]: React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;
->   }
-> }
-> ```
-
-### SSR — Nuxt 3 / Vue
-
-```vue
-<!-- components/AdiaKit.client.vue  ← .client.vue = Nuxt client-only -->
-<script setup>
-import { onMounted } from 'vue';
-
-onMounted(async () => {
-  await import('@adia-ai/web-components');
-  await import('@adia-ai/web-modules/shell');     // per-cluster, NOT the full barrel
-  // CSS — REQUIRED (see §CSSPolicy)
-  await import('@adia-ai/web-components/css');
-  await import('@adia-ai/web-modules/shell/admin-shell.css');
-  const { installIconLoadersForRegistered } =
-    await import('@adia-ai/web-components/core/icons');
-  const modules = import.meta.glob(
-    '../node_modules/@phosphor-icons/core/assets/regular/*.svg',
-    { query: '?raw', import: 'default', eager: true }
-  );
-  installIconLoadersForRegistered(modules);
-});
-</script>
-```
-
-Table / chart wiring inside `onMounted`:
-
-```vue
-<script setup>
-import { ref, onMounted } from 'vue';
-const tableRef = ref(null);
-const toolbarRef = ref(null);
-
-onMounted(() => {
-  toolbarRef.value.table = tableRef.value;
-  tableRef.value.columns = [ /* ... */ ];
-  tableRef.value.data = [ /* ... */ ];
-});
-</script>
-
-<template>
-  <card-ui>
-    <header><span slot="heading">Users</span></header>
-    <section style="padding: 0">
-      <table-toolbar-ui ref="toolbarRef" />
-      <table-ui ref="tableRef" sortable striped />
-    </section>
-  </card-ui>
-</template>
-```
-
-### SSR — SvelteKit
-
-```svelte
-<!-- src/lib/AdiaKit.svelte -->
-<script>
-  import { onMount } from 'svelte';
-
-  onMount(async () => {
-    await import('@adia-ai/web-components');
-    await import('@adia-ai/web-modules/shell');   // per-cluster, NOT the full barrel
-    // CSS — REQUIRED (see §CSSPolicy)
-    await import('@adia-ai/web-components/css');
-    await import('@adia-ai/web-modules/shell/admin-shell.css');
-    const { installIconLoadersForRegistered } =
-      await import('@adia-ai/web-components/core/icons');
-    const modules = import.meta.glob(
-      '../node_modules/@phosphor-icons/core/assets/regular/*.svg',
-      { query: '?raw', import: 'default', eager: true }
-    );
-    installIconLoadersForRegistered(modules);
-  });
-</script>
-```
-
-Table wiring:
-
-```svelte
-<script>
-  import { onMount } from 'svelte';
-  let tableEl, toolbarEl;
-
-  onMount(() => {
-    toolbarEl.table = tableEl;
-    tableEl.columns = [ /* ... */ ];
-    tableEl.data = [ /* ... */ ];
-  });
-</script>
-
-<table-toolbar-ui bind:this={toolbarEl}></table-toolbar-ui>
-<table-ui bind:this={tableEl} sortable striped></table-ui>
-```
-
-### SSR — Astro
-
-Astro static (SSG): use `client:load` on any island containing AdiaUI.
-Import CSS from the `<script>` block (Astro's Vite handles `.css`
-imports the same as Next/Nuxt/Svelte). **Do not** use
-`<link rel="stylesheet" href="/node_modules/...">` — that path is
-fragile (works in dev via the proxy, breaks in build because Vite
-hashes asset paths) and bypasses the package's `exports` map.
-
-```astro
----
-// pages/dashboard.astro — static, safe
----
-<html>
-<head>
-  <title>Dashboard</title>
-</head>
-<body>
-  <!-- Static AdiaUI markup is fine: custom elements self-init in browser -->
-  <card-ui>
-    <header><span slot="heading">Hello</span></header>
-    <section><button-ui text="Click me" variant="primary"></button-ui></section>
-  </card-ui>
-
-  <!-- JS wiring (table.columns, chart.data) needs a client island -->
-  <UsersTable client:load />
-
-  <script>
-    // CSS — REQUIRED (see §CSSPolicy); use the package exports, never
-    // a /node_modules/ root-absolute href.
-    import '@adia-ai/web-components/css';
-    // Add per-shell CSS if you mount one of the shells:
-    // import '@adia-ai/web-modules/shell/admin-shell.css';
-
-    import '@adia-ai/web-components';
-    // Per-cluster shell registration (NOT the full barrel):
-    // import '@adia-ai/web-modules/shell';
-
-    import { installIconLoadersForRegistered } from '@adia-ai/web-components/core/icons';
-    const m = import.meta.glob('../node_modules/@phosphor-icons/core/assets/regular/*.svg',
-      { query: '?raw', import: 'default', eager: true });
-    installIconLoadersForRegistered(m);
-  </script>
-</body>
-</html>
-```
-
-### Framework property binding patterns
-
-When you're not using AdiaUI's own `html` template engine, properties
-must be set imperatively — attribute strings alone are not reactive.
-
-```jsx
-// React — useEffect + ref
-const ref = useRef(null);
-useEffect(() => { if (ref.current) ref.current.value = myValue; }, [myValue]);
-return <slider-ui ref={ref} onChange={e => setMyValue(e.detail.value)} />;
-```
-
-```html
-<!-- Vue — colon binding sets JS property, not HTML attribute -->
-<input-ui :value="myValue" @change="myValue = $event.detail.value"></input-ui>
-```
-
-```svelte
-<!-- Svelte — bind:value for two-way, or on:change for one-way -->
-<input-ui bind:value={myValue}></input-ui>
-```
-
-### The §Flows patterns — which need adaptation?
-
-| §Flow pattern | SPA | SSR |
-|---|---|---|
-| Auth card markup | ✓ verbatim | ✓ verbatim (static markup) |
-| Registration / onboarding shell | ✓ verbatim | ✓ verbatim (form submits to server route) |
-| Admin / editor shell markup | ✓ verbatim | ✓ verbatim (static structure) |
-| `<script>` router wiring | ✓ verbatim | ✗ → `useEffect` / `onMounted` / `onMount` |
-| Table `.columns` + `.data` wiring | ✓ verbatim | ✗ → client lifecycle hook |
-| Chart `.data` wiring | ✓ verbatim | ✗ → client lifecycle hook |
-| `data-stream-*` attributes | ✓ verbatim | ✓ verbatim (guarded internally) |
-| Icon loader `import '@adia-ai/web-components'` | ✓ top-level | ✗ → dynamic import in lifecycle hook |