Beépített alkalmazások

Az ElyOS rendszer 6 beépített alkalmazással érkezik, amelyek a rendszer alapvető funkcióit biztosítják. Minden alkalmazás egy egységes keretrendszert használ, amely biztosítja a konzisztens felhasználói élményt és a könnyű bővíthetőséget.

Alkalmazás keretrendszer

Az ElyOS alkalmazások egy egységes keretrendszert használnak, amely biztosítja a konzisztens felhasználói élményt, a könnyű bővíthetőséget és a hatékony állapotkezelést. A keretrendszer központi eleme az AppShell (állapotkezelő logika) és az AppLayout (vizuális struktúra), amelyek együttműködve kezelik a menünavigációt, a dinamikus komponens betöltést és az alkalmazás életciklusát.

Architektúra áttekintés

Minden beépített alkalmazás ugyanazt az architektúrát követi:

┌───────────────────────────────────────────────────────┐
│                      AppLayout                        │
│  ┌──────────────┐  ┌──────────────────────────────┐   │
│  │              │  │                              │   │
│  │  AppSideBar  │  │     AppContentArea           │   │
│  │              │  │  (dinamikus komponens)       │   │
│  │  ┌────────┐  │  │                              │   │
│  │  │ Menu   │  │  │  - Vite glob import          │   │
│  │  │ Items  │  │  │  - Lazy loading              │   │
│  │  └────────┘  │  │  - Props átadás              │   │
│  │              │  │                              │   │
│  └──────────────┘  └──────────────────────────────┘   │
│                    ┌──────────────────────────────┐   │
│                    │      ActionBar               │   │
│                    │  (opcionális funkciósáv)     │   │
│                    └──────────────────────────────┘   │
└───────────────────────────────────────────────────────┘

Adatfolyam:

AppShell kezeli az állapotot (aktív menüpont, komponens, props)
AppSideBarMenu megjeleníti a menüt és kezeli a kattintásokat
AppShell.handleMenuItemClick() frissíti az állapotot
AppContentArea detektálja a változást és betölti az új komponenst
Komponens renderelődik a props-okkal és beállíthatja az ActionBar-t

Főbb komponensek

1. AppShell

Az AppShell a központi állapotkezelő és logikai réteg minden alkalmazáshoz. Felelős:

Menü állapot kezelése (aktív menüpont, kinyitott szülők)
Komponens betöltés koordinálása
Navigáció kezelése
Lokalizáció (többnyelvű menü)
Paraméter kezelés (URL hash alapú navigáció)

Használat:

<script lang="ts">
  import { createAppShell } from '$lib/apps/appShell.svelte';
  import menuData from './menu.json';

  const shell = createAppShell({
    appName: 'settings',
    menuData: menuData as RawMenuItem[]
  });
</script>

Főbb funkciók:

menuItems - Lokalizált menüpontok (reaktív)
activeMenuItem - Aktív menüpont href-je
activeComponent - Betöltött komponens neve
componentProps - Komponensnek átadott props
expandedParents - Kinyitott szülő menüpontok
handleMenuItemClick(item) - Menüpont kattintás kezelő
navigateTo(component, props, menuHref) - Programozott navigáció

2. AppLayout

Az AppLayout a vizuális keretrendszer, amely összeköti az összes UI elemet:

<AppLayout
  {shell}
  namespaces={['settings', 'common']}
  maxWidthClass="max-w-3xl"
  sidebarWidth={230}
  searchable={false}
/>

Paraméterek:

shell - AppShell példány (kötelező)
namespaces - i18n namespace-ek (automatikusan hozzáadja a ‘common’-t)
maxWidthClass - Tartalom max szélessége (Tailwind osztály)
sidebarWidth - Sidebar szélessége pixelben vagy ‘auto’
searchable - Keresés engedélyezése a menüben
isPlugin - Plugin mód (komponensek API-n keresztül töltődnek)

Funkciók:

I18nProvider beállítása
Sidebar és menü renderelése
Tartalom terület kezelése
ActionBar megjelenítése (ha van tartalom)
Automatikus ActionBar törlés komponens váltáskor

3. AppSideBar és AppSideBarMenu

A bal oldali sidebar tartalmazza a navigációs menüt és biztosítja az összecsukható/kinyitható funkcionalitást.

AppSideBar funkciók:

Összecsukható sidebar (ChevronLeft/Right gomb)
Állapot mentése localStorage-ba (app-sidebar-collapsed-${appName})
Konfigurálható szélesség (pixelben vagy ‘auto’)
Smooth animációk (CSS transitions)
Gradient háttér (light/dark mode támogatás)

AppSideBarMenu funkciók:

Hierarchikus menü struktúra: Szülő-gyerek kapcsolatok támogatása
Összecsukható szülők: Chevron ikon animációval
Aktív menüpont kiemelés: Vizuális feedback
Keresés: Opcionális keresőmező a menüpontok szűréséhez
Smooth animációk: CSS Grid alapú (grid-template-rows: 0fr → 1fr)
Ikon támogatás: UniversalIcon komponens (Lucide/Phosphor)
Separator támogatás: Elválasztó vonalak a menüben
Rejtett menüpontok szűrése: hidden: true mezővel

Menü állapot kezelés:

// Kinyitott menüpontok
let expandedItems = $state<Set<string>>(new Set());

// Felhasználó által manuálisan bezárt menüpontok
// (ezeket nem nyitjuk ki automatikusan)
let manuallyClosed = $state<Set<string>>(new Set());

Automatikus kinyitás:

Kereséskor: Minden szülő menüpont kinyílik, amely tartalmaz találatot
Aktív menüpont: A szülő menüpontok automatikusan kinyílnak
Inicializáláskor: Az initialExpandedParents prop alapján

Keresés működése:

Felhasználó beír egy keresőszót
filterItemsBySearch() rekurzívan szűri a menüpontokat
getExpandedParentsForSearch() meghatározza a kinyitandó szülőket
expandedItems frissül, a menü animáltan kinyílik
manuallyClosed törlődik (keresés közben minden látható)

Menüpont kattintás:

function handleClick(item: MenuItem, event: MouseEvent) {
  event.preventDefault();
  onItemClick?.(item);  // AppShell.handleMenuItemClick()
}

4. AppContentArea

A tartalmi terület dinamikusan tölti be és rendereli a komponenseket. Ez a keretrendszer egyik legfontosabb része, amely biztosítja a lazy loading-ot és a hatékony komponens kezelést.

Működési elv:

Vite glob import az összes app komponenshez:

const appComponentModules = import.meta.glob('/src/apps/*/components/*.svelte');
// Eredmény: { '/src/apps/settings/components/ProfileSettings.svelte': () => Promise<Module> }

Komponens betöltés igény szerint (lazy loading):

const moduleKey = `/src/apps/${appName}/components/${componentName}.svelte`;
const moduleLoader = appComponentModules[moduleKey];

if (!moduleLoader) {
  throw new Error(`Komponens nem található: ${componentName}`);
}

const module = await moduleLoader();
loadedComponent = module.default;

Komponens renderelés props-okkal:

{#if loadedComponent}
  {@const Component = loadedComponent}
  <Component {...props} />
{/if}

Reaktív betöltés:

$effect(() => {
  const currentComponent = component;

  // Guard: ne töltsünk be újra, ha már töltünk vagy már be van töltve
  if (isLoadingComponent) return;

  if (currentComponent && currentComponent !== lastLoadedComponent) {
    untrack(() => loadComponent(currentComponent));
  } else if (!currentComponent) {
    untrack(() => {
      loadedComponent = null;
      error = null;
      lastLoadedComponent = null;
    });
  }
});

Állapotok:

loading - Betöltés folyamatban (spinner megjelenítése)
error - Hiba történt (hibaüzenet megjelenítése)
loadedComponent - Betöltött komponens (renderelés)
placeholder - Nincs kiválasztott menüpont (üres állapot)
isLoadingComponent - Guard flag (dupla betöltés elkerülése)
lastLoadedComponent - Utoljára betöltött komponens neve (cache)

Plugin támogatás:

Plugin komponensek API-n keresztül töltődnek be és Web Component-ként renderelődnek:

async function loadPluginComponent(componentName: string) {
  // 1. Komponens kód lekérése API-n keresztül
  const response = await fetch(`/api/plugins/${appName}/components/${componentName}`);
  const code = await response.text();

  // 2. Kód futtatása (factory function létrehozása)
  const script = document.createElement('script');
  script.textContent = code;
  document.head.appendChild(script);

  // 3. Factory meghívása és custom element tag name lekérése
  const factoryName = `${appName.replace(/-/g, '_')}_Component_${componentName}`;
  const componentFactory = window[factoryName];
  const componentInfo = componentFactory();

  // 4. Custom element renderelése
  loadedComponent = {
    __pluginTagName: componentInfo.tagName,
    __pluginProps: props
  };
}

Hibakezelés:

Komponens nem található → Hibaüzenet megjelenítése
Betöltési hiba → Konzol log + hibaüzenet
Plugin betöltési hiba → Factory function hiányzik

Performance optimalizáció:

Lazy loading: Csak az aktív komponens töltődik be
Cache: lastLoadedComponent alapján elkerüljük az újratöltést
Guard flag: isLoadingComponent megakadályozza a dupla betöltést
untrack(): Elkerüljük a végtelen ciklusokat

5. ActionBar

Az ActionBar egy opcionális funkciósáv az alkalmazás alján, ahol a komponensek gombokat és egyéb vezérlőket helyezhetnek el.

Használat komponensben:

<script lang="ts">
  import { getActionBar } from '$lib/apps/actionBar.svelte';
  import { Button } from '$lib/components/ui/button';

  const actionBar = getActionBar();

  // ActionBar tartalom beállítása
  actionBar.set(myActions);
</script>

{#snippet myActions()}
  <Button onclick={handleSave}>Mentés</Button>
  <Button variant="outline" onclick={handleCancel}>Mégse</Button>
{/snippet}

API:

content - Aktuális snippet (null ha nincs)
set(snippet) - Snippet beállítása
clear() - Tartalom törlése

Automatikus törlés:

Az AppLayout automatikusan törli az ActionBar tartalmát komponens váltáskor, így nem kell manuálisan kezelni.

Menü struktúra (menu.json)

Minden alkalmazás rendelkezik egy menu.json fájllal, amely definiálja a menüpontokat. A menü hierarchikus struktúrát támogat, lokalizálható és jogosultság alapú szűrést biztosít.

Példa menü struktúra:

[
  {
    "labelKey": "menu.profile",
    "href": "#profile",
    "icon": "User",
    "component": "ProfileSettings"
  },
  {
    "labelKey": "menu.desktop",
    "href": "#",
    "icon": "Monitor",
    "children": [
      {
        "labelKey": "menu.general",
        "href": "#desktop",
        "icon": "Settings",
        "component": "DesktopSettings"
      },
      {
        "labelKey": "menu.background",
        "href": "#background",
        "icon": "Image",
        "component": "BackgroundSettings"
      }
    ]
  },
  {
    "separator": true
  },
  {
    "labelKey": "menu.advanced",
    "href": "#advanced",
    "icon": "Settings",
    "component": "AdvancedSettings",
    "requiredPermission": "settings.advanced.view",
    "hideWhen": "notDevMode"
  }
]

Menüpont mezők:

Mező	Típus	Kötelező	Leírás
`labelKey`	string	Igen	Fordítási kulcs (pl. “menu.profile” → “settings.menu.profile”)
`href`	string	Igen	URL hash (pl. “#profile”). Szülő menüpontoknál lehet ”#“
`icon`	string	Nem	Ikon neve (Lucide vagy Phosphor, pl. “User”, “Settings”)
`component`	string	Nem*	Komponens neve a `components/` mappából (pl. “ProfileSettings”)
`children`	array	Nem	Almenüpontok tömbje (hierarchikus menü)
`separator`	boolean	Nem	Elválasztó vonal (true esetén más mező nem kell)
`requiredPermission`	string	Nem	Szükséges jogosultság (pl. “settings.advanced.view”)
`hideWhen`	string	Nem	Feltételes elrejtés (pl. “notDevMode”, “singleLocale”)
`props`	object	Nem	Komponensnek átadott props (pl. `{ "mode": "advanced" }`)
`hidden`	boolean	Nem	Menüpont elrejtése (true esetén nem jelenik meg)

* A component mező kötelező, ha a menüpontnak nincs children mezője és nem separator.

Menü lokalizáció:

A menü automatikusan lokalizálódik a localizeMenuItems() függvény segítségével:

// Namespace: appName (pl. 'settings')
// Kulcs: labelKey (pl. 'menu.profile')
// Teljes kulcs: 'settings.menu.profile'

const menuItems = $derived.by(() => {
  void translationStore.currentLocale;
  return localizeMenuItems(appName, rawMenuData);
});

Fordítások hozzáadása:

INSERT INTO translations (namespace, key, locale, value) VALUES
  ('settings', 'menu.profile', 'hu', 'Profil'),
  ('settings', 'menu.profile', 'en', 'Profile'),
  ('settings', 'menu.desktop', 'hu', 'Asztal'),
  ('settings', 'menu.desktop', 'en', 'Desktop');

Hierarchikus menü:

A children mező használatával többszintű menüt hozhatunk létre:

{
  "labelKey": "menu.desktop",
  "href": "#",
  "icon": "Monitor",
  "children": [
    {
      "labelKey": "menu.general",
      "href": "#desktop",
      "component": "DesktopSettings"
    }
  ]
}

Fontos szabályok:

Szülő menüpont href-je: Ha van children, akkor a href lehet ”#” (nem navigál)
Szülő menüpont component-je: Opcionális, ha van, akkor a szülőre kattintva is betöltődik
Gyerek menüpontok: Mindig kell component mező
Separator: Csak separator: true mező kell, más nem
Ikon: Opcionális, de ajánlott a jobb UX érdekében

Jogosultság alapú szűrés:

A requiredPermission mező használatával korlátozhatjuk a menüpontok láthatóságát:

{
  "labelKey": "menu.advanced",
  "href": "#advanced",
  "component": "AdvancedSettings",
  "requiredPermission": "settings.advanced.view"
}

Ha a felhasználónak nincs meg a szükséges jogosultsága, a menüpont automatikusan elrejtésre kerül.

Feltételes elrejtés:

A hideWhen mező használatával feltételesen rejthetünk el menüpontokat:

{
  "labelKey": "menu.language",
  "href": "#language",
  "component": "LanguageSettings",
  "hideWhen": "singleLocale"
}

Támogatott értékek:

"singleLocale" - Elrejti, ha csak egy nyelv van a rendszerben
"notDevMode" - Elrejti, ha nem fejlesztői módban fut a rendszer

Komponens életciklus

Alkalmazás indítása
- AppShell létrehozása
- Menü betöltése és lokalizáció
- Alapértelmezett menüpont kiválasztása (első component-tel rendelkező)
Menüpont kattintás
- handleMenuItemClick(item) meghívása
- activeComponent frissítése
- componentProps beállítása
- URL hash frissítése (section paraméter)
Komponens betöltés
- AppContentArea $effect triggerelése
- Vite glob import használata
- Aszinkron komponens betöltés
- Komponens renderelés props-okkal
ActionBar kezelés
- Komponens beállítja az ActionBar-t (actionBar.set())
- ActionBar megjelenik az alkalmazás alján
- Komponens váltáskor automatikus törlés
Navigáció
- URL hash változás (#profile → #security)
- AppShell $effect detektálja a változást
- Megfelelő menüpont aktiválása
- Komponens betöltés

Többnyelvűség

A menü automatikusan lokalizálódik a localizeMenuItems függvény segítségével:

// Namespace: appName (pl. 'settings')
// Kulcs: labelKey (pl. 'menu.profile')
// Teljes kulcs: 'settings.menu.profile'

const menuItems = $derived.by(() => {
  void translationStore.currentLocale;
  return localizeMenuItems(appName, rawMenuData);
});

Fordítások:

INSERT INTO translations (namespace, key, locale, value) VALUES
  ('settings', 'menu.profile', 'hu', 'Profil'),
  ('settings', 'menu.profile', 'en', 'Profile');

Jogosultság ellenőrzés

A menüpontok automatikusan szűrődnek a felhasználó jogosultságai alapján:

// menu.json
{
  "labelKey": "menu.advanced",
  "requiredPermission": "settings.advanced.view",
  // ...
}

Ha a felhasználónak nincs meg a szükséges jogosultsága, a menüpont nem jelenik meg.

URL paraméterek

Az alkalmazások támogatják a section paramétert az URL hash-ben:

// Ablak megnyitása section paraméterrel
windowManager.openWindow('settings', 'Beállítások', settingsApp, {
  section: 'profile'  // → #profile menüpont aktiválása
});

Az AppShell automatikusan detektálja a section paramétert és aktiválja a megfelelő menüpontot.