talearchitect-api 1.0.0

package/README.md

@@ -0,0 +1,100 @@
+# TaleArchitect API Definitions
+
+![NPM Version](https://img.shields.io/npm/v/talearchitect-api?style=flat-square)
+![License](https://img.shields.io/npm/l/talearchitect-api?style=flat-square)
+
+Este pacote contém as definições de tipo TypeScript (`.d.ts`) para o desenvolvimento de plugins para o **TaleArchitect**.
+
+Ao instalar este pacote, seu editor de código (VS Code, etc.) fornecerá **Autocomplete (IntelliSense)**, documentação inline e verificação de tipos para a variável global `app`.
+
+> **Nota:** Este pacote contém apenas tipos. A lógica de execução é fornecida nativamente pelo aplicativo TaleArchitect.
+
+## 📦 Instalação
+
+Na pasta do seu plugin, execute:
+
+```bash
+npm install --save-dev talearchitect-api
+```
+
+## 🚀 Como Usar
+
+Existem duas formas principais de habilitar o autocomplete no seu projeto:
+
+**Opção 1:** Usando Diretiva de Referência (Mais Simples)
+Adicione esta linha no topo do seu arquivo main.js:
+
+```bash
+///<reference types="talearchitect-api" />
+
+app.ui.toast("Olá Mundo!");
+```
+
+**Opção 2:** Usando jsconfig.json (Recomendado)
+
+Crie um arquivo jsconfig.json na raiz da pasta do seu plugin. Isso habilita o autocomplete em todos os arquivos do projeto sem precisar adicionar a linha de referência em cada um.
+
+```bash
+{
+  "compilerOptions": {
+    "checkJs": true
+  },
+  "include": [
+    "node_modules/talearchitect-api/index.d.ts",
+    "**/*.js"
+  ]
+}
+```
+
+## 📚 Visão Geral da API
+O objeto global app expõe as seguintes funcionalidades:
+
+```app.commands```
+
+Execute comandos nativos ou registre seus próprios comandos na Paleta (Ctrl+K).
+
+```bash
+app.commands.register('meu:comando', () => { ... });
+```
+
+```app.data```
+
+Acesso de leitura aos dados do projeto (Personagens, Locais, Eventos, Calendário).
+
+```bash
+const chars = await app.data.getCharacters();
+```
+
+```app.factory```
+
+Criação segura de entidades (com suporte automático a Undo/Ctrl+Z).
+
+```bash
+const id = await app.factory.createCharacter("Novo Herói");
+```
+
+```app.ui```
+
+Interação com o usuário (Toasts, Alertas, Confirmações).
+
+```bash
+app.ui.toast("Sucesso!", "success");
+```
+
+```app.events```
+
+Escute eventos do ciclo de vida do aplicativo.
+
+```bash
+app.events.on('project:save', () => { ... });
+```
+
+```app.context```
+
+Descubra o estado atual da interface (qual aba está ativa, nível de zoom, etc).
+
+```bash
+if (app.context.getActiveTab() === 'map') { ... }
+```
+
+https://github.com/MateusRNM/TaleArchitect - Repositório principal do aplicativo.

package/index.d.ts

@@ -0,0 +1,126 @@
+export type UUID = string;
+
+export interface Month {
+    name: string;
+    days: number;
+}
+
+export interface Time {
+    day: number;
+    month: number;
+    year: number;
+    hour?: number;
+    minute?: number;
+}
+
+export interface Coordinates {
+    x: number;
+    y: number;
+}
+
+export interface Character {
+    id: UUID;
+    name: string;
+    image: string | null;
+    description: string;
+    createdAt: string;
+    [key: string]: any;
+}
+
+export interface Location {
+    id: UUID;
+    name: string;
+    description: string;
+    coordinates: Coordinates;
+    [key: string]: any;
+}
+
+export interface Connection {
+    id: UUID;
+    name: string;
+    description: string;
+    fromLocationId: UUID;
+    toLocationId: UUID;
+    [key: string]: any;
+}
+
+export interface Event {
+    id: UUID;
+    name: string;
+    description: string;
+    locationId: UUID;
+    date: Time;
+    characters: UUID[];
+    [key: string]: any;
+}
+
+export interface MapView {
+    x: number;
+    y: number;
+    k: number;
+}
+
+export interface MapStateSnapshot {
+    view: MapView;
+    selectedLocationId: string | null;
+    selectedConnectionId: string | null;
+}
+
+export interface TimelineStateSnapshot {
+    view: 'list' | 'form';
+    selectedEventId: string | null;
+    scrollY: number;
+}
+
+export interface FullUIState {
+    map: MapStateSnapshot;
+    timeline: TimelineStateSnapshot;
+}
+
+export type ToastType = 'success' | 'error' | 'info';
+
+export interface AppAPI {
+
+    readonly version: string;
+
+    commands: {
+        execute(id: string, args?: any): Promise<void>;
+        register(id: string, handler: (args: any) => void, options?: any): void;
+    };
+
+    data: {
+        getCharacters(): Promise<Character[]>;
+        getLocations(): Promise<Location[]>;
+        getConnections(): Promise<Connection[]>;
+        getEvents(): Promise<Event[]>;
+        getCalendar(): Promise<{ months: Month[] }>;
+        getCurrentDate(): Promise<Time | null>;
+    };
+
+    factory: {
+        createCharacter(name: string, description?: string): Promise<UUID | null>;
+        createEvent(name: string, date: Time, description?: string): Promise<UUID | null>;
+        createLocation(name: string, description?: string, x?: number, y?: number): Promise<UUID | null>;
+    };
+
+    ui: {
+        toast(msg: string, type?: ToastType, duration?: number): void;
+        alert(msg: string, title?: string): Promise<void>;
+        confirm(msg: string, title?: string): Promise<boolean>;
+    };
+
+    events: {
+        on(event: string, callback: (data: any) => void): void;
+    };
+
+    context: {
+        getActiveTab(): string;
+        getStates(): FullUIState;
+    };
+}
+
+declare global {
+    const app: AppAPI;
+}
+
+export {};

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "talearchitect-api",
+  "version": "1.0.0",
+  "description": "Type definitions for TaleArchitect plugins",
+  "types": "index.d.ts",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": ["talearchitect", "plugin", "api", "types"],
+  "author": "Mateus RNM",
+  "license": "MIT",
+  "peerDependencies": {}
+}