@smartsoft001-mobilems/claude-plugins 2.90.0 → 2.91.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartsoft001-mobilems/claude-plugins",
-  "version": "2.90.0",
+  "version": "2.91.0",
   "publishConfig": {
     "access": "public"
   },

package/plugins/mobilems/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "mobilems",
   "description": "MobilEMS-specific Claude Code skills (MuzaCMS / MobileMS indexer API)",
-  "version": "2.90.0"
+  "version": "2.91.0"
 }

package/plugins/mobilems/skills/mobilems-search/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: mobilems-search
+description: Style and wire the MobilEMS global search results page (`/wyszukaj/:text`) to a museum's approved mockup — the tabbed results view over objects, collections and news, plus the searchbar that feeds it. Use whenever the user wants to build, restyle or fix search, the results tabs, the searchbar, result cards or pagination, or asks to "zrób wyszukiwarkę", "ostyluj wyniki wyszukiwania", "popraw wyszukiwanie globalne", "dodaj zakładkę wyników". The results page ships with the project skeleton, so this skill is about the design, the per-module tabs and the interaction details — not about creating a feature library.
+user-invocable: true
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion
+---
+
+# MobilEMS global search
+
+Bring the search results page up to the museum's mockup and make its tabs
+actually work. The page (`apps/web/src/app/pages/search`) and its route come
+with the skeleton; what varies per museum is the styling and which feature
+modules contribute tabs.
+
+Search is the page where cross-module wiring goes wrong most often, because a
+tab is owned by the module that renders it while the frame is owned by the app.
+Both sides have to hold up their end.
+
+## Precondition
+
+Run `scripts/detect-search.sh <workspace-root>` — confirms the results page and
+the `wyszukaj/:text` route exist. If they do not, the project predates the
+skeleton; build the foundation with `mobilems-project-init` first.
+
+## Framework first — read before writing components
+
+1. `packages/shared/angular/README.md` (installed as
+   `node_modules/@smartsoft001-mobilems/angular/README.md`)
+2. `libs/shared/angular/README.md` — the app's own shared lib
+
+| Do not hand-roll | Use |
+| --- | --- |
+| a tab strip | `TabsComponent` / `Tab` from the shared lib (the page already imports it) |
+| result cards | the module's own list-item components (`objects-list-item`, news/collection cards) |
+| "next page" behaviour | the shared `NextPageComponent`, same pattern as the module lists |
+| a search input | `app-objects-searchbar` / the shared searchbar variants |
+
+Forking a result card for search is the classic mistake: the card then drifts
+from the module's list and the museum ends up with two visually different
+representations of the same object.
+
+## Steps
+
+1. **Read the mockup** in `docs/mockups/` — the searchbar and the result list
+   item are usually exported as separate design-system components rather than a
+   full screen, so match the component and keep the page layout consistent with
+   the rest of the portal.
+2. **Tabs come from modules.** Each feature module registers a child route under
+   `wyszukaj/:text` (its search module) and the page builds its tab list from
+   what is registered. When a tab is missing, fix it in that module's skill
+   scope, not by hardcoding the tab here.
+3. **Direct navigation to a tab must work.** Opening `/wyszukaj/wazy/aktualnosci`
+   straight from a link — not by clicking through — has to land on that tab with
+   results loaded. This broke repeatedly (MOB-1052…1056) because the active tab
+   was derived from click state instead of the URL.
+4. **Interaction details that the audit checks:** debounce the full-text input
+   by 250 ms (`@debounce(250)` from `lodash-decorators`) so every keystroke does
+   not hit the API; give the results page its own `title`; keep pagination
+   targets at the WCAG 2.5.8 minimum size.
+5. **Translations.** Labels, tab names, the result counter and the empty state
+   all go through translation keys in both `pl` and `en`; run
+   `npm run check:translations` (or `npx mobilems-check-translations`).
+   The results page invents new keys more often than other pages — it is the one
+   place where a phrase like "found N results" has no counterpart elsewhere.
+6. **Verify** — `scripts/verify-search.sh <workspace-root>`: route, tab wiring,
+   debounce, framework components, translation coverage.
+
+## Known pitfalls
+
+- **Empty query and no-results states.** Both must render something deliberate;
+  a blank page reads as a broken site.
+- **Result counts per tab.** If the mockup shows counts, they have to come from
+  the facade's total, not from the length of the loaded page.
+- **Keyboard path.** Type, press Enter, arrow through tabs, reach a result and
+  open it — all without a mouse. Search is the most keyboard-driven page in the
+  portal.
+- **Phrase in the heading.** Show the searched phrase, escaped — museum
+  collections contain quotes and angle brackets in titles.
+
+## Notes
+
+- This skill owns the search frame and its styling. A missing or broken tab
+  belongs to the feature module that should register it.
+- Bundled `scripts/` ship automatically. Do not hand-edit `plugin.json`.

package/plugins/mobilems/skills/mobilems-search/scripts/detect-search.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+#
+# detect-search.sh <workspace-root>
+#
+# Precondition for mobilems-search: the skeleton's results page and route exist.
+set -eu
+ROOT="${1:?usage: detect-search.sh <workspace-root>}"
+cd "$ROOT" 2>/dev/null || { echo "ERROR: no such dir: $ROOT" >&2; exit 2; }
+
+miss() { echo "BRAK FUNDAMENTU: $1 — uruchom najpierw /mobilems:project-init" >&2; exit 3; }
+
+[ -f apps/web/src/app/pages/search/search.component.ts ] || miss "pages/search/search.component.ts"
+grep -qE "path: *['\"]wyszukaj" apps/web/src/app/app.routes.ts || miss "trasa wyszukaj w app.routes.ts"
+echo "OK: szkielet wyszukiwarki obecny"

package/plugins/mobilems/skills/mobilems-search/scripts/verify-search.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+#
+# verify-search.sh <workspace-root>
+#
+# Post-condition for mobilems-search: route + tabs from modules, URL-driven
+# active tab, debounce, framework components, translations. bash 3.2 safe.
+# Env: REF_ROOT=<reference-repo> enables the completeness diff.
+set -eu
+ROOT="${1:?usage: verify-search.sh <workspace-root>}"
+cd "$ROOT" 2>/dev/null || { echo "ERROR: no such dir: $ROOT" >&2; exit 2; }
+
+fail=0
+pass() { echo "  PASS: $1"; }
+bad()  { echo "  FAIL: $1" >&2; fail=1; }
+
+ROUTES=apps/web/src/app/app.routes.ts
+SEARCH=apps/web/src/app/pages/search
+
+echo "== Trasa i zakładki =="
+grep -qE "path: *['\"]wyszukaj" "$ROUTES" && pass "trasa wyszukaj" || bad "brak trasy wyszukaj"
+# Zakładki rejestrują moduły dziedzinowe jako dzieci wyszukaj/:text.
+# Moduły wnoszą zakładki jako *SearchModule — liczymy je bez zgadywania,
+# gdzie dokładnie kończy się blok trasy (formatowanie bywa różne).
+TABS="$(grep -cE "[A-Za-z]+SearchModule" "$ROUTES" || true)"
+[ "${TABS:-0}" -ge 1 ] && pass "moduły rejestrują zakładki wyników ($TABS)" || bad "żaden moduł nie rejestruje zakładki pod wyszukaj/:text"
+
+echo "== Aktywna zakładka z URL, nie ze stanu kliknięcia =="
+# Bug MOB-1052…1056: wejście linkiem prosto na zakładkę nie działało.
+if grep -rqE "ActivatedRoute|router\.events|url" "$SEARCH"/search.component.ts 2>/dev/null; then
+  pass "komponent czyta zakładkę z routingu"
+else
+  bad "zakładka nie jest wyprowadzana z URL — wejście bezpośrednie się zepsuje"
+fi
+
+echo "== Komponenty frameworka =="
+grep -rq "TabsComponent" "$SEARCH" 2>/dev/null && pass "zakładki przez TabsComponent" || bad "własny pasek zakładek zamiast TabsComponent"
+FORK="$(grep -rlE "class .*(SearchResultItem|SearchCard)Component" apps/web/src libs 2>/dev/null || true)"
+if [ -n "$FORK" ]; then
+  bad "własny kafel wyników zamiast komponentu modułu (rozjedzie się z listą):"
+  printf '        %s\n' $FORK >&2
+else
+  pass "wyniki renderowane komponentami modułów"
+fi
+
+echo "== Interakcja =="
+grep -rq "debounce" apps/web/src libs 2>/dev/null && pass "debounce wyszukiwania obecny" || bad "brak debounce — każde naciśnięcie klawisza uderza w API"
+
+echo "== Translacje =="
+if npx --no-install mobilems-check-translations --help >/dev/null 2>&1 || [ -x node_modules/.bin/mobilems-check-translations ]; then
+  if npx --no-install mobilems-check-translations ${REF_ROOT:+--reference "$REF_ROOT"}; then
+    pass "translacje bez martwych referencji"
+  else
+    bad "braki w translacjach — popraw wypisane wyżej"
+  fi
+else
+  echo "  SKIP: mobilems-check-translations niedostępny w tym projekcie (starsza linia frameworka)"
+fi
+
+echo
+if [ "$fail" = 0 ]; then echo "VERIFY: all checks passed."; else echo "VERIFY: FAILED — fix the items above and re-run." >&2; fi
+exit "$fail"

package/plugins/mobilems/skills/mobilems-static-pages/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: mobilems-static-pages
+description: Style and wire the MobilEMS static CMS pages (`/strona/:id`, `/strona/:id/:slug`, `/kontakt`) to a museum's approved mockup — the About / Accessibility statement / Privacy policy / Contact pages every portal has. Use whenever the user wants to build, restyle or fix the static pages, the CMS page template, the contact page, or asks to "zrób strony statyczne", "podłącz strony z CMS", "ostyluj stronę Kontakt", "strony O nas / deklaracja dostępności / polityka prywatności". The page scaffolding ships with the project skeleton, so this skill is about making it match the design and render real CMS content — not about creating a feature library.
+user-invocable: true
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion
+---
+
+# MobilEMS static pages
+
+Bring the museum's static pages up to its approved mockup. Unlike the feature
+modules, there is nothing to scaffold: `apps/web/src/app/pages/page` (CMS page
+template + resolver) and `pages/contact` come with the skeleton, and their
+routes are already registered. What differs per museum is the design and the
+CMS wiring — which is exactly what tends to be missing when these pages are
+built ad hoc.
+
+## Precondition
+
+Run `scripts/detect-pages.sh <workspace-root>`. It confirms the skeleton pages
+and their routes exist. If they do not, the project predates the skeleton that
+ships them — build them from `mobilems-project-init` first rather than
+hand-rolling here, so every museum keeps the same structure.
+
+## Framework first — read before writing components
+
+Static pages are mostly composition, so almost everything you need already
+exists. Re-implementing it is a defect, not a shortcut:
+
+1. `packages/shared/angular/README.md` (installed as
+   `node_modules/@smartsoft001-mobilems/angular/README.md`) — the framework API catalog
+2. `libs/shared/angular/README.md` — the app's own shared lib
+
+| Do not hand-roll | Use |
+| --- | --- |
+| a rich-text renderer for CMS body HTML | the page template's existing content block + widget map |
+| per-page galleries / sliders | the widget content-type components (`WIDGET` group) |
+| menu and footer links | the API menu configuration (see pitfalls — hardcoding them was a reported bug) |
+| meta/OG tags | `SeoService` / `MetaService` |
+
+## Steps
+
+1. **Read the mockup.** Exports live in `docs/mockups/`; read them (Read) rather
+   than guessing from the Figma link. Note the container width, heading scale,
+   spacing rhythm and how the page header/hero differs from the module pages.
+2. **CMS data — render everything the API sends.** The page payload carries more
+   than a title and body: `image`, `backgroundImage`, `links`, `slides`.
+   A field that arrives and is not rendered reads to the client as a missing
+   feature, so walk the resolver's payload and account for each field.
+3. **Contact page.** The contact page's CMS id is per-instance, so the `kontakt`
+   route resolves it through the menu rather than a constant. Keep it that way —
+   a hardcoded id works on one museum and breaks on the next.
+4. **Translations.** Every static label goes through a key in the `CONTACT`
+   group (plus `COMMON` where it is genuinely shared); no Polish literals in
+   templates, and both `pl` and `en` filled. Run `npm run check:translations`
+   (or `npx mobilems-check-translations`) — a raw `CONTACT.something` on screen
+   is one of the most visible defects a user can hit.
+5. **Verify** — `scripts/verify-pages.sh <workspace-root>`: asserts the routes,
+   the resolver wiring, translation coverage and that no menu/footer link is
+   hardcoded. Fix and re-run.
+
+## Known pitfalls (fix while styling, not after)
+
+- **Hardcoded navigation.** Footer and menu entries come from the API config.
+  Two separate bugs (MOB-1044, MOB-1071) traced back to links pasted into
+  templates — they render fine on the museum you are looking at and 404 on the
+  next one.
+- **One `h1` per page.** The CMS title is the `h1`; a second one in the hero or
+  breadcrumb is a WCAG 1.3.1 violation that the audit will catch.
+- **360 px without horizontal scroll.** Long CMS words and wide embedded media
+  are the usual culprits; test the narrow viewport before calling it done.
+- **Dark / high-contrast mode.** The page renders client HTML, so contrast
+  overrides must reach nested CMS markup (`[&_p]`, `[&_a]`, headings) — checking
+  only the page chrome misses the body text.
+- **Empty states.** A CMS page with no body, no image or no links must still
+  render a sane layout; museums publish half-filled pages more often than not.
+
+## Notes
+
+- This skill touches the static pages only. Feature modules (objects,
+  collections, news) have their own skills and their own libraries.
+- Bundled `scripts/` ship automatically. Do not hand-edit `plugin.json`.

package/plugins/mobilems/skills/mobilems-static-pages/scripts/detect-pages.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+#
+# detect-pages.sh <workspace-root>
+#
+# Precondition for mobilems-static-pages: the skeleton's static pages and their
+# routes exist. bash 3.2 safe.
+set -eu
+ROOT="${1:?usage: detect-pages.sh <workspace-root>}"
+cd "$ROOT" 2>/dev/null || { echo "ERROR: no such dir: $ROOT" >&2; exit 2; }
+
+miss() { echo "BRAK FUNDAMENTU: $1 — uruchom najpierw /mobilems:project-init" >&2; exit 3; }
+
+[ -f apps/web/src/app/pages/page/page.component.ts ] || miss "pages/page/page.component.ts"
+[ -f apps/web/src/app/pages/page/page.resolver.ts ]  || miss "pages/page/page.resolver.ts"
+grep -q "strona/:id" apps/web/src/app/app.routes.ts   || miss "trasa strona/:id w app.routes.ts"
+echo "OK: szkielet stron statycznych obecny"

package/plugins/mobilems/skills/mobilems-static-pages/scripts/verify-pages.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+#
+# verify-pages.sh <workspace-root>
+#
+# Post-condition for mobilems-static-pages: routes wired, CMS payload rendered,
+# navigation not hardcoded, translations complete. bash 3.2 safe.
+# Env: REF_ROOT=<reference-repo> enables the completeness diff.
+set -eu
+ROOT="${1:?usage: verify-pages.sh <workspace-root>}"
+cd "$ROOT" 2>/dev/null || { echo "ERROR: no such dir: $ROOT" >&2; exit 2; }
+
+fail=0
+pass() { echo "  PASS: $1"; }
+bad()  { echo "  FAIL: $1" >&2; fail=1; }
+
+ROUTES=apps/web/src/app/app.routes.ts
+PAGE=apps/web/src/app/pages/page
+
+echo "== Trasy =="
+grep -q "strona/:id" "$ROUTES"       && pass "trasa strona/:id" || bad "brak trasy strona/:id"
+grep -q "strona/:id/:slug" "$ROUTES" && pass "trasa strona/:id/:slug (SEO slug)" || bad "brak trasy ze slugiem"
+grep -qE "path: *'kontakt'" "$ROUTES" && pass "trasa kontakt" || bad "brak trasy kontakt"
+grep -q "pageResolver" "$ROUTES"     && pass "resolver podpięty do trasy" || bad "trasa bez pageResolver"
+
+echo "== Treść z CMS =="
+# Pola, których pominięcie klient odbiera jako brak funkcji.
+for field in image links; do
+  grep -rq "$field" "$PAGE" 2>/dev/null && pass "szablon używa pola $field" || bad "pole $field z CMS nigdzie nierenderowane"
+done
+
+echo "== Nawigacja z konfiguracji, nie z kodu =="
+# Twarde ścieżki do stron CMS w szablonach = bug MOB-1044/MOB-1071.
+HARD="$(grep -rlE "routerLink=\"/strona/[0-9]" apps/web/src libs 2>/dev/null || true)"
+if [ -n "$HARD" ]; then
+  bad "twarde linki do stron CMS (id jest per-instancja):"
+  printf '        %s\n' $HARD >&2
+else
+  pass "brak twardych linków do stron CMS"
+fi
+
+echo "== Dostępność =="
+H1="$(grep -rc "<h1" "$PAGE"/*.html 2>/dev/null | awk -F: '{s+=$2} END {print s+0}')"
+[ "${H1:-0}" -le 1 ] && pass "co najwyżej jeden h1 w szablonie strony" || bad "kilka h1 w szablonie strony ($H1) — WCAG 1.3.1"
+
+echo "== Translacje =="
+if npx --no-install mobilems-check-translations --help >/dev/null 2>&1 || [ -x node_modules/.bin/mobilems-check-translations ]; then
+  if npx --no-install mobilems-check-translations --groups "CONTACT" ${REF_ROOT:+--reference "$REF_ROOT"}; then
+    pass "grupa CONTACT kompletna"
+  else
+    bad "braki w translacjach — popraw wypisane wyżej"
+  fi
+else
+  echo "  SKIP: mobilems-check-translations niedostępny w tym projekcie (starsza linia frameworka)"
+fi
+
+echo
+if [ "$fail" = 0 ]; then echo "VERIFY: all checks passed."; else echo "VERIFY: FAILED — fix the items above and re-run." >&2; fi
+exit "$fail"