====== Pack-Struktura ======

Struktura i pravila za WvdS Control/Component Packove - i interne i od trećih strana.

===== Pregled =====

Packovi su distribucijski format za:
  * **Controls** - UI-elementi (Button, TextBox, DateEdit, ...)
  * **Components** - Ne-vizualne komponente (Timer, DataSource, ...)

<note>Packovi omogućuju instalaciju Controls **bez modifikacije WvdS-Core**.</note>

===== Struktura direktorija =====

==== Interni WvdS Packovi ====

**Putanja:** ''~/packs/''

<code>
~/packs/
├── controls/
│   ├── button/
│   │   └── pack.wvds.json
│   ├── textbox/
│   │   └── pack.wvds.json
│   └── dateedit/
│       └── pack.wvds.json
└── components/
    ├── timer/
    │   └── pack.wvds.json
    └── datasource/
        └── pack.wvds.json
</code>

==== Packovi trećih strana ====

**Putanja:** ''~/vendor-packs/''

<code>
~/vendor-packs/
├── index.json                          # Instalacijski indeks
├── oss/                                 # Open-Source Packovi
│   └── {vendor}/
│       └── {pack}/
│           ├── pack.wvds.json          # Pack-Manifest (OBAVEZNO)
│           ├── src/                    # Pascal-Units
│           │   ├── Model.pas
│           │   └── Renderers/
│           │       ├── TUI.pas
│           │       ├── Desktop.pas
│           │       └── Web.pas
│           ├── vsix/                   # Design-Time Resursi
│           ├── docs/                   # API-Dokumentacija
│           └── license/                # OSS-Licenca
│               └── LICENSE.txt
└── proprietary/                        # Vlasnički Packovi
    └── {vendor}/
        └── {pack}/
            ├── pack.wvds.json
            ├── src/ ili bin/          # Izvorni kod ili Binaries
            ├── vsix/
            ├── docs/
            ├── license/
            │   ├── LICENSE.txt
            │   └── EULA.txt
            └── integrity/              # Provjera integriteta
                ├── SHA256SUMS
                └── SIGNATURE.asc       # Opcionalno
</code>

===== Pack-Manifest =====

Svaki Pack zahtijeva ''pack.wvds.json'' datoteku:

<code javascript>
{
  "id": "dateedit",
  "vendor": "wvds",
  "version": "0.1.0",
  "license": "MIT",
  "description": "Polje za unos datuma s Kalender-Popupom",

  "xml": {
    "namespace": "wvds",
    "tag": "DateEdit"
  },

  "model": {
    "unit": "WvdS.UI.Controls.Editors.DateEdit",
    "class": "TWvdSDateEdit"
  },

  "renderers": {
    "tui": {
      "unit": "WvdS.UI.TUI.Renderers.DateEdit",
      "class": "TWvdSTUIDateEditRenderer"
    },
    "desktop": {
      "unit": "WvdS.UI.Desktop.Renderers.DateEdit",
      "class": "TWvdSDesktopDateEditRenderer"
    },
    "web": {
      "unit": "WvdS.UI.Web.Renderers.DateEdit",
      "class": "TWvdSWebDateEditRenderer"
    }
  },

  "targetCaps": {
    "requires": ["keyboard"],
    "optional": ["mouse", "popup", "touch"]
  },

  "dependencies": [],

  "compatibility": {
    "wvds": ">=0.1.0"
  }
}
</code>

==== Manifest-Polja ====

^ Polje ^ Obavezno ^ Opis ^
| ''id'' | Da | Jedinstveni Pack-Identifikator |
| ''vendor'' | Da | Vendor-ID (npr. "wvds", "dx", "ms") |
| ''version'' | Da | Semantic Version |
| ''license'' | Da | Identifikator licence (SPDX) |
| ''xml.namespace'' | Da | PXAML-Namespace |
| ''xml.tag'' | Da | PXAML-Tag-Naziv |
| ''model.unit'' | Da | Pascal-Unit za Model |
| ''model.class'' | Da | Naziv klase Modela |
| ''renderers'' | Da | Renderer po Targetu |
| ''targetCaps'' | Ne | Potrebne/opcionalne Capabilities |
| ''dependencies'' | Ne | Ovisnosti o drugim Packovima |
| ''compatibility'' | Ne | WvdS-verzijski zahtjev |

===== Instalacijski indeks =====

**Putanja:** ''~/vendor-packs/index.json''

<code javascript>
{
  "version": "1.0",
  "installed": [
    {
      "vendor": "dx",
      "pack": "dateedit-pro",
      "version": "2.1.0",
      "license": "proprietary",
      "location": "proprietary/dx/dateedit-pro",
      "enabledTargets": ["desktop", "web"],
      "installedAt": "2026-01-13T10:30:00Z",
      "integrity": {
        "sha256": "abc123..."
      }
    },
    {
      "vendor": "jw",
      "pack": "charts",
      "version": "1.0.0",
      "license": "oss",
      "location": "oss/jw/charts",
      "enabledTargets": ["desktop", "web"],
      "installedAt": "2026-01-12T14:00:00Z"
    }
  ]
}
</code>

===== CLI-Naredbe =====

==== Instaliranje Packa ====

<code bash>
wvds-build pack install \
  --from /path/to/packdir \
  --to ~/vendor-packs \
  --enable tui,desktop,web
</code>

==== Deinstaliranje Packa ====

<code bash>
wvds-build pack uninstall \
  --vendor dx \
  --pack dateedit-pro
</code>

==== Popis instaliranih Packova ====

<code bash>
wvds-build pack list
</code>

Izlaz:

<code>
Installed Packs:
  dx/dateedit-pro  2.1.0  [desktop, web]  proprietary
  jw/charts        1.0.0  [desktop, web]  oss
</code>

===== Konvencije imenovanja =====

<note warning>Packovi trećih strana NE SMIJU koristiti ''TWvdS*'' prefiks!</note>

^ Vendor ^ Prefiks klase ^ Primjer ^
| WvdS (interno) | ''TWvdS*'' | ''TWvdSDateEdit'' |
| DevExpress | ''TDx*'' | ''TDxDateEdit'' |
| Microsoft | ''TMs*'' | ''TMsFluentButton'' |
| JWorks | ''TJw*'' | ''TJwChartView'' |

===== Provjera integriteta =====

Vlasnički Packovi moraju podržavati provjeru integriteta:

**SHA256SUMS:**

<code>
a1b2c3d4... src/Model.pas
e5f6g7h8... src/Renderers/Desktop.pas
i9j0k1l2... src/Renderers/Web.pas
</code>

**Opcionalni potpis:**

<code bash>
# Kreiranje potpisa
gpg --armor --detach-sign SHA256SUMS

# Provjera potpisa
gpg --verify SHA256SUMS.asc SHA256SUMS
</code>

===== Važna pravila =====

<code>
NIKAKVE promjene na WvdS-Core tijekom instalacije:
  ✗ ~/sources/common/WvdS/** NE SMIJE se uređivati
  ✗ Nikakve ručne "uses" promjene u Core-Units

Pack-Izolacija:
  ✓ Svaki Pack je samostalan
  ✓ Deinstalacija uklanja sve Pack-datoteke
  ✓ Index.json se atomski ažurira

Backward Compatibility:
  ✓ Pack-Manifest-Format je verzioniran
  ✓ Stariji Packovi funkcioniraju s novijim WvdS-verzijama
  ✓ Breaking Changes se signaliziraju Manifest-verzijom
</code>

===== Kreiranje Pack-a treće strane =====

==== Korak 1: Kreiranje Skeletona ====

<code bash>
mkdir -p ~/vendor-packs/oss/myvendor/mycontrol/{src,docs,license}
</code>

==== Korak 2: Pisanje Manifesta ====

<code bash>
cat > ~/vendor-packs/oss/myvendor/mycontrol/pack.wvds.json << 'EOF'
{
  "id": "mycontrol",
  "vendor": "myvendor",
  "version": "1.0.0",
  "license": "MIT",
  "xml": {
    "namespace": "mv",
    "tag": "MyControl"
  },
  "model": {
    "unit": "MyVendor.Controls.MyControl",
    "class": "TMvMyControl"
  },
  "renderers": {
    "web": {
      "unit": "MyVendor.Web.Renderers.MyControl",
      "class": "TMvWebMyControlRenderer"
    }
  }
}
EOF
</code>

==== Korak 3: Kreiranje Pascal-Units ====

  * Model-Unit u ''src/''
  * Renderer-Units u ''src/Renderers/''

==== Korak 4: Dodavanje licence ====

<code bash>
cp LICENSE.txt ~/vendor-packs/oss/myvendor/mycontrol/license/
</code>

==== Korak 5: Registracija ====

<code bash>
wvds-build pack install \
  --from ~/vendor-packs/oss/myvendor/mycontrol \
  --enable web
</code>

===== Vidi također =====

  * [[.:control-entwicklung|Razvoj Controla]]
  * [[.:build-pipeline|Build-Pipeline]]
  * [[.:architektur|Pregled arhitekture]]