weg-shared-layout 0.0.3 → 0.0.5

package/readme.md

@@ -10,147 +10,147 @@ Install:
 npm i weg-shared-layout
 ```
 
+## How it works
+
+`<weg-footer>` is a **presentational** Web Component: it does **not** fetch data. Your app loads layout data however you like (REST, GraphQL, SSR, etc.), then passes the object into the component via the **`data` property** (not a string HTML attribute).
+
+The payload shape matches the sample file **`dummy-data.json`**, shipped with the package:
+
+- **Import:** `import layout from 'weg-shared-layout/dummy-data.json'` (enable `resolveJsonModule` in TypeScript if needed).
+- **In this repo:** [`src/assets/dummy-data.json`](src/assets/dummy-data.json)
+
+Use that JSON as fixture data to see the footer working, or as a reference for your own API responses. Only `social.platform` values `LinkedIn`, `Instagram`, `TikTok`, and `YouTube` render an icon; items with missing or invalid fields are dropped.
+
 ## Using in Angular
 
-Register custom elements (recommended in `main.ts`):
+Assumes Angular 17+ with **standalone** components (default for `ng new`).
+
+### 1. Install
+
+```bash
+npm i weg-shared-layout
+```
+
+### 2. Register custom elements (once, before bootstrap)
+
+In `src/main.ts`, call `defineCustomElements()` **before** `bootstrapApplication` so the browser recognises `<weg-footer>`.
 
 ```ts
+import { bootstrapApplication } from '@angular/platform-browser';
 import { defineCustomElements } from 'weg-shared-layout/loader';
 
+import { appConfig } from './app/app.config';
+import { App } from './app/app';
+
 defineCustomElements();
+
+bootstrapApplication(App, appConfig).catch((err) => console.error(err));
 ```
 
-Allow custom elements in the module that uses them:
+### 3. Allow custom elements in templates
 
-```ts
-import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
+Add `schemas: [CUSTOM_ELEMENTS_SCHEMA]` to every `@Component` whose template uses `<weg-footer>` (it does not cascade from the root through `router-outlet` children).
 
-@NgModule({
-  // ...
-  schemas: [CUSTOM_ELEMENTS_SCHEMA],
-})
-export class AppModule {}
-```
+### 4. Pass data with property binding
 
-Use in a template (standard):
+Use **`[data]="..."`** so Angular sets the element’s JavaScript `data` property (Stencil `@Prop()`), not an HTML attribute.
 
-```html
-<weg-footer
-  variant="standard"
-  company-name="WEG"
-  company-number="12345678"
-  social-links-src="/assets/footer-social-links.json"
-  standard-links-src="/assets/footer-standard-links.json"
-></weg-footer>
-```
+Example with the bundled sample payload:
 
-Use in a template (additional):
+```ts
+// src/app/app.ts
+import { Component, CUSTOM_ELEMENTS_SCHEMA, signal } from '@angular/core';
+import { RouterOutlet } from '@angular/router';
+import layoutFixture from 'weg-shared-layout/dummy-data.json';
+
+@Component({
+  selector: 'app-root',
+  imports: [RouterOutlet],
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  templateUrl: './app.html',
+  styleUrl: './app.css',
+})
+export class App {
+  protected readonly layoutData = signal(layoutFixture);
+}
+```
 
 ```html
-<weg-footer
-  variant="additional"
-  company-name="WEG"
-  company-number="12345678"
-  social-links-src="/assets/footer-social-links.json"
-  additional-groups-src="/assets/footer-additional-groups.json"
-></weg-footer>
+<!-- src/app/app.html -->
+<router-outlet />
+<weg-footer [data]="layoutData()"></weg-footer>
 ```
 
-## Using in React
+In production, replace `layoutFixture` with data from your own services; keep the same object shape as `dummy-data.json`.
 
-Install:
+### Troubleshooting
 
-```bash
-npm i weg-shared-layout
-```
+| Symptom | Cause / fix |
+| --- | --- |
+| `'weg-footer' is not a known element` | Add `schemas: [CUSTOM_ELEMENTS_SCHEMA]` on the component whose template contains `<weg-footer>`. |
+| Footer missing or empty box | `defineCustomElements()` not called before bootstrap, or `data` not set / wrong shape — compare with `dummy-data.json`. |
+| SSR: `document is not defined` | Guard `defineCustomElements()` with `typeof window !== 'undefined'` or `isPlatformBrowser`. |
 
-Register custom elements (pick one):
+### TypeScript typings
 
 ```ts
-// Option A (recommended): loader registers all components
-import { defineCustomElements } from 'weg-shared-layout/loader';
-
-defineCustomElements();
+/// <reference types="weg-shared-layout/dist/types/components" />
 ```
 
-Or:
+### Legacy `NgModule`
 
-```ts
-// Option B: import package bundle (also registers, depending on output target configuration)
-import 'weg-shared-layout';
-```
+Add `CUSTOM_ELEMENTS_SCHEMA` once on the module that declares components using `<weg-footer>`. `defineCustomElements()` in `main.ts` is still required.
 
-### Next.js (App Router) note
+## Using in React
 
-Stencil custom elements must be registered **in the browser**. If you’re using Next.js `app/` (App Router), don’t import/register Stencil components from a Server Component.
+Register once (for example in your app entry):
 
-Instead, register them in a Client Component, for example:
+```ts
+import { defineCustomElements } from 'weg-shared-layout/loader';
 
-```tsx
-// app/components/WegFooterClient.tsx
-"use client";
-
-import "weg-shared-layout/weg-footer";
-
-export function WegFooterClient() {
-  return (
-    <weg-footer
-      variant="standard"
-      company-name="WEG"
-      company-number="12345678"
-      social-links-src="/assets/footer-social-links.json"
-      standard-links-src="/assets/footer-standard-links.json"
-    />
-  );
-}
+defineCustomElements();
 ```
 
-Use the footer (standard):
+Pass an object via a **ref** (or use React 19+ property handling) so you set the DOM property, not a string attribute:
 
 ```tsx
+import { useEffect, useRef, useState } from 'react';
 import 'weg-shared-layout/weg-footer';
+import layoutFixture from 'weg-shared-layout/dummy-data.json';
 
-export function App() {
-  return (
-    <weg-footer
-      variant="standard"
-      company-name="WEG"
-      company-number="12345678"
-      social-links-src="/assets/footer-social-links.json"
-      standard-links-src="/assets/footer-standard-links.json"
-    />
-  );
-}
-```
-
-Use the footer (additional):
+export function SiteFooter() {
+  const ref = useRef<HTMLElement & { data?: unknown }>(null);
+  const [layout, setLayout] = useState(layoutFixture);
 
-```tsx
-import 'weg-shared-layout/weg-footer';
+  useEffect(() => {
+    if (ref.current) ref.current.data = layout;
+  }, [layout]);
 
-export function App() {
-  return (
-    <weg-footer
-      variant="additional"
-      company-name="WEG"
-      company-number="12345678"
-      social-links-src="/assets/footer-social-links.json"
-      additional-groups-src="/assets/footer-additional-groups.json"
-    />
-  );
+  return <weg-footer ref={ref} />;
 }
 ```
 
-### React TypeScript typings
+Swap `layoutFixture` / `setLayout` for your own data loading. **Next.js App Router:** register and assign `data` only in a Client Component (`"use client"`).
 
-Stencil generates `components.d.ts` in this repo, but React does not automatically pick up custom element typings. In consuming React apps, add a `global.d.ts` (or similar) that references your package’s generated types:
+### React TypeScript
 
 ```ts
 /// <reference types="weg-shared-layout/dist/types/components" />
 ```
 
-If your app still complains about JSX intrinsic elements, you can also augment `JSX.IntrinsicElements` in that same file (varies by React/TS setup).
+## Plain HTML / vanilla JS
 
-### Note on `*-src` JSON URLs
+With a bundler that resolves `node_modules` imports:
+
+```html
+<weg-footer id="footer"></weg-footer>
+<script type="module">
+  import { defineCustomElements } from 'weg-shared-layout/loader';
+  import layout from 'weg-shared-layout/dummy-data.json';
+
+  defineCustomElements();
+  document.getElementById('footer').data = layout;
+</script>
+```
 
-`social-links-src`, `standard-links-src`, and `additional-groups-src` are fetched by the component at runtime, so the JSON files must be **served by the host app** (e.g. Angular’s `src/assets/`), or be a full `https://...` URL.
+Otherwise, copy `dummy-data.json` to your static assets, `fetch` it, parse JSON, then assign **`element.data`**. You can also pass a JSON string on the **`data` attribute**; the component parses it the same way as an object `data` property.

package/src/assets/dummy-data.json

@@ -0,0 +1,20 @@
+{
+  "header": {},
+  "footer": {
+    "social": [
+      { "platform": "LinkedIn", "href": "https://www.linkedin.com/" },
+      { "platform": "Instagram", "href": "https://www.instagram.com/" },
+      { "platform": "TikTok", "href": "https://www.tiktok.com/" },
+      { "platform": "YouTube", "href": "https://www.youtube.com/" }
+    ],
+    "standardLinks": [
+      { "label": "About Us", "href": "/about" },
+      { "label": "Privacy Policy", "href": "/privacy" },
+      { "label": "Terms of Use", "href": "/terms" },
+      { "label": "Cookie Policy", "href": "/cookies" },
+      { "label": "Accessibility Statement", "href": "/accessibility" }
+    ],
+    "credits": "Warwick Employment Group is a department of the Campus and Commercial Services Group at the University of Warwick.",
+    "copyright": "Copyright © Warwick Employment Group."
+  }
+}

package/dist/cjs/app-globals-V2Kpy_OQ.js

@@ -1,5 +0,0 @@
-'use strict';
-
-const globalScripts = () => {};
-
-exports.globalScripts = globalScripts;