@smartsoft001-mobilems/claude-plugins 2.120.0 → 2.121.0

package/README.md

@@ -20,6 +20,7 @@ Run them in this order for a new museum app — `/smart:scaffold-nx-workspace`
 | `mobilems-project-init` | The MobilEMS foundation: deps, Tailwind, runtime env, `app.config` providers, shared lib, static pages, app shell, `.claude`. No feature modules. |
 | `mobilems-objects` | `libs/museum-objects` + the `/obiekty` route |
 | `mobilems-object-collections` | `libs/museum-collections` + the `/kolekcje` route |
+| `mobilems-creators` | `libs/museum-creators` + the creators route (`/tworcy` or `/artysci`) and the creators search tab |
 | `mobilems-articles` | A parametrized (NAME + TEMPLATE) article module — news, education, … |
 | `mobilems-thematic-publications` | `libs/museum-thematic-paths` + the `/sciezki-tematyczne` route |
 | `mobilems-events` | `libs/museum-events` + the `/wydarzenia` route (booking flow) |

package/package.json

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

package/plugins/mobilems/.claude-plugin/README.md

@@ -13,6 +13,7 @@ Run order for a new museum app: `/smart:scaffold-nx-workspace` → `mobilems-pro
 | Skill | `mobilems-project-init` | The MobilEMS foundation — deps, Tailwind, SSR + translations runtime, `app.config` providers, shared lib, static pages, app shell, `.claude`. Produces NO feature modules |
 | Skill | `mobilems-objects` | Museum objects module — `libs/museum-objects` (domain + shell/angular) + the `/obiekty` route |
 | Skill | `mobilems-object-collections` | Collections module — `libs/museum-collections` + the `/kolekcje` route |
+| Skill | `mobilems-creators` | Creators (artists) — `libs/museum-creators` + the creators route and search tab |
 | Skill | `mobilems-articles` | A parametrized (NAME + TEMPLATE) article-backed content module; run once per content type |
 | Skill | `mobilems-thematic-publications` | Thematic paths — `libs/museum-thematic-paths` + the `/sciezki-tematyczne` route |
 | Skill | `mobilems-events` | Events + booking flow — `libs/museum-events` + the `/wydarzenia` route |

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.120.0"
+  "version": "2.121.0"
 }

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

@@ -0,0 +1,138 @@
+---
+name: mobilems-creators
+description: Add the museum CREATORS (artists) feature module to a MobilEMS app initialized with mobilems-project-init. Use whenever the user wants to add / scaffold / wire the creators module, the artists index (letters, groups, jump-to), the filtered artists list, the creator details page, the creator card, or the artists tab of the global search, or asks to "dodaj moduł twórców / artystów". Creates libs/museum-creators (or the museum's own name, e.g. museum-artists), registers the creators route (/tworcy or /artysci), and adds the creators npm packages. Requires the MobilEMS foundation to exist first.
+user-invocable: true
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion
+---
+
+# MobilEMS creators module
+
+Add the **creators** (twórcy / artyści) feature module to a MobilEMS app whose foundation was built by
+`mobilems-project-init`. This skill builds the `libs/museum-creators` library (the museum may name it
+`museum-artists`), its routes and its pages on top of the framework bases, and wires the creators path and the
+search tab.
+
+The framework shares **logic only**: every page is an `@Directive() abstract class` with no template. The museum
+writes its own HTML and styles. There is no generator (one reference consumer, so YAGNI): the library is written by
+hand from the reference below.
+
+## Precondition
+
+The MobilEMS foundation must exist (`SharedModule.forRoot` in `app.config.ts`, a populated shared-lib barrel). If it
+does not, tell the user to run `/mobilems:project-init` first. Ask the user for:
+
+- the library name (default `museum-creators`) and the route (`/tworcy`, or `/artysci` as in sztuki);
+- the museum's API host. **The index base needs the prefixes endpoint and `lastNameSw`, which only the staging
+  API has** (`api-muza.muzeumsztuki.pl` does not). Without them build the list on `CreatorsCatalogBaseComponent`
+  (see the README's "Which list base?").
+
+The reference is the sztuki museum's `libs/museum-artists` (routes, pages, templates, search tab). Read it for the
+templates; take the logic from the framework bases. Its artist page (MOB-1972/1963) was ported into
+`CreatorDetailsBaseComponent` from sztuki `8f698f6`, but sztuki's own `item.component` does not extend the base yet:
+copy its template, not its class.
+
+## Framework first — MANDATORY
+
+Read these before writing ANY component, service, pipe, directive or helper, and reuse what they
+list — re-implementing framework code is a defect, not a shortcut:
+
+0. [**The Framework API index**](https://github.com/smartsoft001/mobilems-framework/blob/main/README.md#-framework-api) — the map of every package to
+   its catalog. Start here when you do not already know which package owns what.
+1. The framework API catalog — `packages/shared/angular/README.md` in this repo, installed as
+   `node_modules/@smartsoft001-mobilems/angular/README.md` in a museum app ([browse](https://github.com/smartsoft001/mobilems-framework/blob/main/packages/shared/angular/README.md)).
+2. [`packages/creators/README.md`](https://github.com/smartsoft001/mobilems-framework/blob/main/packages/creators/README.md) — this module's package catalog: services, URL tools, the bases,
+   the "Which list base?" table and the API notes
+3. `libs/shared/angular/README.md` — the app's own shared lib (built by `mobilems-project-init`)
+
+| Do not hand-roll                                                                             | Use                                                                                                                            |
+| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| the creators HTTP calls, letter filtering, id normalisation                                  | `CreatorsService` (`getPage`, `getAll`, `getByLetter`, `getPrefixes`, `getByIndexPrefix`, `getById`, `getWorks`, `getRelated`) |
+| the letter index: letters, two-letter groups, `#fragment`, focus                             | `CreatorsIndexBaseComponent`                                                                                                   |
+| the mobile "go to" panel                                                                     | `CreatorsJumpToBaseComponent`                                                                                                  |
+| the filtered list (name, birth range, sort, paging)                                          | `CreatorsCatalogBaseComponent` + `CreatorsFiltersBaseComponent` (modal)                                                        |
+| the creator card (name, years, roles, image, link)                                           | `CreatorCardBaseComponent`                                                                                                     |
+| the details page (biography fold, portrait, related strips, contents, share, prev/next, SEO) | `CreatorDetailsBaseComponent`                                                                                                  |
+| the search tab (phrase, paging, page size)                                                   | `CreatorsSearchListBaseComponent`                                                                                              |
+| query urls, name/roles/years formatting, letter grouping, details link                       | `creatorsListUrl`, `creatorDisplayName`, `creatorRoles`, `groupCreatorsByLetter`, `creatorDetailsCommands`                     |
+| a masonry grid                                                                               | `<smart-mobilems-masonry-grid>` (`MasonryGridComponent`), with `provideBrowserMasonry()`                                       |
+| meta / OG tags, media urls                                                                   | `MuseumSeoService` (the bases call it), `FileUrlService` (the card and details call it)                                        |
+
+Anything the framework genuinely lacks goes into `libs/shared/angular` **once** (and into its README) — never a
+per-module copy.
+
+## Steps
+
+1. **npm deps** — add `@smartsoft001-mobilems/creators-domain`, `@smartsoft001-mobilems/creators-shell-angular`,
+   `@smartsoft001-mobilems/creators-shell-dtos` (match the installed mobilems line). The details base types works as
+   `MsObject`, so `@smartsoft001-mobilems/objects-domain` must be present too. Resolve versions at run time; do not
+   `npm install` unless asked.
+2. **Library** — create `libs/museum-creators` with a `shell/angular` project (sztuki's `museum-artists` has one) and the tsconfig path
+   `@<PREFIX>/museum-creators/shell/angular`, mirroring the other `libs/museum-*` libs. The models come from the
+   framework packages, so the museum needs no domain project of its own.
+3. **Routes** — the module routes, in this order (the details page takes the canonical `:id/:slug` and the bare `:id`):
+
+   ```ts
+   export const routes: Route[] = [
+     { path: ':id/:slug', component: ItemComponent },
+     { path: ':id', component: ItemComponent },
+     { path: '', component: ListComponent },
+   ];
+   ```
+
+   Register the lazy route in `apps/web/src/app/app.routes.ts` (`/tworcy` or `/artysci`).
+
+4. **Pages** — each extends a framework base; the museum supplies the template. Overridable members are read lazily,
+   so declare them as `protected override readonly`:
+   - `ListComponent extends CreatorsIndexBaseComponent`: override `creatorsIndexAnchorBase` (default `'tworcy'`; the
+     museum's route name, so `#Ba` links match) and `creatorsIndexSeo` (an `ICreatorsListSeo` with the museum's
+     translation keys). Put the button that opens the jump-to panel under the `#filtersButton` template ref. Its
+     template shows the results view while the base's `filtered()` is `true` and the letter index otherwise; do not
+     re-parse `?filter=` yourself.
+   - `ResultsComponent extends CreatorsCatalogBaseComponent` for `?filter=`: `super({ persistKey, listPath, seo })`.
+     Pair it with `FiltersComponent extends CreatorsFiltersBaseComponent` (do not bind Escape again, the base does).
+     Bind the modal's `(applied)` to `applyFilter($event)`: it navigates to `listPath?filter=…` (the url is the source
+     of truth); "reset filters" is `clearAllFilters()`, which navigates back to the index.
+     Offer only the filters the API supports: **name and birth date from-to** (no death date, collection or tags).
+   - `IndexFiltersMobileComponent extends CreatorsJumpToBaseComponent` (the jump-to panel; override
+     `creatorsJumpToHeaderSelectors` if the header tags differ from `app-header` / `app-nav-bar`).
+   - `ArtistCardComponent extends CreatorCardBaseComponent`: override `creatorCardPath` (default `'/tworcy'`) and
+     `creatorCardPlaceholder` (default `'/gfx/no-image.png'`).
+   - `ItemComponent extends CreatorDetailsBaseComponent`: override `creatorDetailsPath` (start it with `/`) and
+     `creatorDetailsKeys` (`{ ...CREATOR_DETAILS_KEYS, ... }` with the museum's label and SEO title keys); sanitize
+     the biography html where the template binds it. For result cards in the related strips, set the type parameter
+     (`CreatorDetailsBaseComponent<SearchResultCard>`) and override `creatorDetailsRelatedItem(item, key)`. Tailwind
+     class strings stay in the component; the base has none.
+5. **Search tab** — in `app.config.ts` set `SEARCH_CONFIG_TOKEN` to `{ apiUrl, creators: true }` (adds the creators
+   count; skip it when your `searchMap` already returns a `creators` url, as sztuki's does, since `searchMap` wins
+   anyway), add a `searchRoutes` module for `/wyszukaj/:text/artysci` whose `SearchListComponent` extends
+   `CreatorsSearchListBaseComponent` (the `#results` template ref is the scroll target), and register it as a child of
+   the `wyszukaj/:text` route (sztuki also lists it in its `SEARCH_SECTIONS`). See `mobilems-search` for the frame.
+6. **Section links** — provide `PAGE_SECTION_ROUTES_TOKEN` as `{ ...DEFAULT_PAGE_SECTION_ROUTES, creatorsPath: '/artysci' }`
+   so a CMS "creator" target goes to `[creatorsPath, id]` instead of the objects filter.
+7. **Translations** — add the keys the museum's templates and overrides use (`ARTISTS.*` / `CREATORS.*`, the SEO
+   keys) for BOTH `pl` and `en`; run `npm run check:translations`.
+8. **Verify** — `npx nx build web` (production), the lib's lint and tests, and open `/artysci`, a letter, a
+   `#fragment` link (`/artysci#Ba`), `?filter=`, a details page with prev/next, and the search tab.
+
+## Known pitfalls
+
+- **Empty `q=` / `sw=` empties the list (404).** Always go through `creatorsListUrl` / the service.
+- **Prefixes endpoint and `lastNameSw` are staging-only**; on `api-muza.muzeumsztuki.pl` the index base shows nothing
+  useful. Check the API before choosing the index base.
+- **Death-date range does not work** (the API always answers 404); collection and tags filters are ignored. Leave
+  them out of the filters modal and report them.
+- **Works 404 means none**: do not show an error for a creator without works.
+- **`creator/{id}` is staging-only**: `getById` reads it and falls back to `dictionary/Creator/{id}` on a 404, so the
+  details page works on both hosts, but the portrait, lead artwork, tags, editorial biography and the exhibitions,
+  archives and MS books strips need the profile endpoint. Their parts simply do not render without it.
+- **Prev/next** exist only after a list was shown (`CreatorsListContext`); a deep link has none. Hide the buttons.
+- **Member name clashes**: the bases prefix their private members (`creators…`, `creator…`) so that a subclass can
+  keep its own `route`, `router`, `document`, `translate`. Keep your own names unprefixed and do not reuse a base
+  prefix; a clash shows up as TS2415 in `nx build`, not in Jest.
+- **SSR**: scrolling, focus and the `#fragment` run only in the browser; use the injected `DOCUMENT`, never the
+  `document` global.
+
+## Notes
+
+- This skill builds only the creators module. It never adds other feature modules and never re-runs the foundation.
+- Bundled files ship automatically. Do not hand-edit `plugin.json`.

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

@@ -49,6 +49,11 @@ representations of the same object.
    `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.
+   **Creators tab.** Set `creators: true` in `SEARCH_CONFIG_TOKEN` (default `false`): `SearchService` then also counts
+   `creators` (`dictionary/Creator/search/page/1?maxPerPage=1&q=…`, `ISearchResults.creators`); `searchMap` still
+   overrides the url. The tab's page extends `CreatorsSearchListBaseComponent`
+   (`@smartsoft001-mobilems/creators-shell-angular`, route `wyszukaj/:text/artysci`); the museum writes the view.
+   Build the module with `mobilems-creators`.
 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