gabeszm/weclome-banner
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
weclome-banner/CLAUDE.md

4.7 KiB
Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Projekt áttekintés

Ez egy Discourse fórum téma komponens a Nyíltvilág magyar technológiai közösség számára. Egy egyedi üdvözlő bannert hoz létre, amely csak a főoldalon jelenik meg, és tartalmaz egy hero szekciót keresési funkcióval és kategória navigációs kártyákkal.

Architektúra

Komponens felépítés

A téma komponens három fő fájlból áll:

  1. index.html - HTML sablon az üdvözlő bannerhez (statikus tartalom)
  2. script.js - Discourse API inicializáló, amely kezeli:
    • Az oldal láthatóságának váltását (csak a főoldalon jeleníti meg a bannert)
    • Az egyedi keresőmező renderelését és integrációját a Discourse SearchMenu-jével
    • Mobil detektálást és feltételes renderelést
  3. style.css - Reszponzív stílusok CSS változókkal

Kulcsfontosságú technikai minták

Discourse Plugin API integráció

  • Az apiInitializer-t használja a discourse/lib/api-ból (modern megközelítés)
  • Az api.onPageChange() hookra csatlakozik, hogy URL alapján mutassa/rejtse a bannert
  • Integrálódik a Discourse natív SearchMenu komponensével az api.openSearchMenu() segítségével

Keresési integráció mintája Az egyedi keresőmező a hero szekcióban így működik:

  1. Egyedi input mező renderelése a .search-container konténerbe
  2. Fókuszáláskor/bevitelkor a Discourse natív SearchMenu megnyitása
  3. Értékek szinkronizálása az egyedi input és a natív .search-menu input.search-query között
  4. Űrlap beküldés delegálása a Discourse keresési űrlapjához

Idempotens renderelés A renderSearchInput() függvény ellenőrzi, hogy a keresőmező már létezik-e, mielőtt létrehozná, így megakadályozza a duplikált elemeket, amikor az API többször is alkalmazza az inicializálót.

Mobil kezelés A keresési funkció le van tiltva mobilon (az isMobileView() függvényen keresztül), hogy elkerülje az ütközéseket a Discourse mobil felületével.

Kód minőség és best practice-ek

  • Következetes arrow function használat
  • Angol osztálynevek és kommentek a nemzetközi standardok szerint
  • Optimalizált renderelés egyetlen requestAnimationFrame hívással
  • Accessibility támogatás (role="search", aria-label attribútumok)

Fontos implementációs részletek

Oldal láthatósági logika (script.js:4-13)

  • A banner csak akkor jelenik meg, ha url === "/"
  • Minden más oldalon a banner rejtve van display: none segítségével

Keresés szinkronizáció (script.js:54-60)

  • Az egyedi input értéke szinkronizálva van a Discourse SearchMenu inputjával
  • A Discourse natív keresési funkcióját input esemény kiváltásával aktiválja
  • Egyesített event handler (handleSearchInteraction) a duplikált kód elkerülésére

Optimalizált renderelés (script.js:90-99)

  • Egyetlen requestAnimationFrame hívás a többszörös kísérlet helyett
  • Biztosítja, hogy az elem létezzen akkor is, ha a DOM nem teljesen készen áll

CSS architektúra

Reszponzív töréspontok

  • Asztal: 1100px+
  • Tablet: 900-1099px
  • Mobil: <900px

Grid elrendezés

  • A hero CSS Grid-et használ névvel ellátott területekkel: "content" és "search"
  • A CTA (Call-To-Action) kártyák reszponzív gridet használnak: 1 oszlop (mobil), 2 oszlop (500px+), 4 oszlop (1510px+)
  • Optimalizált grid oszlopok 1fr egységekkel a felesleges calc() helyett

Kulcsfontosságú CSS változók

--primary-color: #e81f2d
--page-bg: #14191f
--card-bg: #1b2028
--text-color: #ddd

Fejlesztési megjegyzések

Komponens tesztelése:

  • A módosítások megtekintése a fórum főoldalára navigálva (/)
  • Oldal láthatóság tesztelése más URL-ekre navigálva
  • Keresés tesztelése az egyedi keresőmezőbe való fókuszálással/gépelés (csak asztalon)

Gyakori módosítások:

  • Üdvözlő szöveg frissítése: index.html 6-20. sor szerkesztése
  • CTA kártyák hozzáadása/eltávolítása: index.html 27-102. sor módosítása
  • Stílusok módosítása: style.css változók vagy szelektorok módosítása
  • Keresési viselkedés módosítása: script.js renderSearchInput() függvény (18-88. sor)

Osztálynevek konvenciói:

  • .search-container - Fő kereső konténer
  • .search-wrapper - Keresőmező wrapper elem
  • .search-input - Keresőmező input elem
  • .cta-* - Call-To-Action kategória kártyák
  • .hero-* - Hero szekció elemei
  • Angol osztálynevek következetesen használva

Discourse API verzió: Ez a komponens a modern apiInitializer mintát használja. Régebbi Discourse verziókkal való munka esetén szükség lehet a withPluginApi használatára helyette.