Crea tu primer panel

Un panel de la comunidad es una carpeta de archivos web con un panel.json en la raíz. Deska lo ejecuta en un sandbox, dentro de su propio panel, y el panel solo habla con Deska a través de window.deska. No hay paso de compilación ni nada que alojar. Necesitas Deska 1.26.0 o posterior en tu computadora, un editor de texto y, para la herramienta de vista previa opcional, Node 20 o posterior.

El panel que vas a crear es un reloj que recuerda una zona horaria. La carpeta terminada es starter/ en deska-panels-examples, junto a catorce ejemplos más grandes, cada uno para enseñar una parte distinta del SDK.

my-first-panel/
  panel.json
  index.html
  app.css
  app.js
  icon.svg

panel.json dice qué es el panel y qué puede hacer. La gente lo lee antes de instalarlo:

{
  "schema": 1,
  "id": "my-first-panel",
  "name": "My First Panel",
  "version": "0.1.0",
  "description": "A small clock that remembers one time zone.",
  "author": "Your name",
  "icon": "icon.svg",
  "category": "other",
  "permissions": [],
  "network": [],
  "sdk": 1,
  "contributes": {
    "panel": { "entry": "index.html", "scope": "workspace", "size": { "width": 300, "height": 200 } }
  }
}

• id tiene de 3 a 40 letras minúsculas, dígitos y guiones. Publicar lo reserva para tu cuenta, y se rechazan los ids que nombran a Deska, a un agente de programación o a un panel incluido.
• permissions y network están vacíos, así que este panel no puede enviar avisos, abrir enlaces, copiar ni conectarse a internet. Pide solo lo que usas.

Cada campo, y cada id que se rechaza, está en la referencia de panel.json.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>My First Panel</title>
  <link rel="stylesheet" href="app.css">
  <script src="/__deska/sdk.js"></script>
  <script type="module" src="app.js"></script>
</head>
<body>
  <main>
    <p class="time" id="time">--:--</p>
    <label class="field">
      <span>Time zone</span>
      <select id="zone"></select>
    </label>
  </main>
</body>
</html>

/__deska/sdk.js no es un archivo de tu carpeta. Deska lo sirve dentro de cada panel, siempre a la par de la app, y define window.deska. Cárgalo como script clásico antes de cualquier cosa que lo use.

El SDK escribe el tema de Deska en tu página como propiedades CSS personalizadas y las actualiza cada vez que cambia el tema o el acento. Úsalas para cada color y el panel combina con el modo oscuro, el claro y cualquier acento:

body {
  margin: 0;
  background: var(--deska-bg);
  color: var(--deska-text);
  font: 13px/1.45 var(--deska-font-ui);
}

select {
  color: var(--deska-text);
  background: var(--deska-surface);
  border: 1px solid var(--deska-border);
  border-radius: var(--deska-radius-small);
}

select:focus-visible {
  outline: 2px solid var(--deska-focus);
}

Los dieciséis tokens y para qué sirve cada uno están en Tokens del tema. El ejemplo Theme Inspector muestra cada uno en vivo, con su contraste.

const $ = (id) => document.getElementById(id)

// 1. Espera a Deska: el panel, el tema, sus permisos, el idioma.
const init = await deska.ready()

// 2. Carga lo que el panel guardó la última vez. null es la primera vez.
let zone = (await deska.storage.get('zone')) ?? Intl.DateTimeFormat().resolvedOptions().timeZone

// 3. Dibuja, y pon la hora bajo el nombre del panel en el lienzo.
function render() {
  const time = new Intl.DateTimeFormat(init.locale, { timeZone: zone, timeStyle: 'short' }).format(new Date())
  $('time').textContent = time
  deska.setTitle(`${zone.split('/').pop().replaceAll('_', ' ')} ${time}`)
}

for (const name of Intl.supportedValuesOf('timeZone')) $('zone').add(new Option(name, name))
$('zone').value = zone

// 4. Guarda cuando la persona cambia algo. Toda llamada puede fallar con un código.
$('zone').addEventListener('change', async () => {
  zone = $('zone').value
  render()
  try {
    await deska.storage.set('zone', zone)
  } catch (err) {
    console.warn(`Could not save: ${err.code}`)
  }
})

// 5. Avanza solo mientras alguien puede ver el panel.
let timer = null
function start() {
  render()
  timer = setInterval(render, 15_000)
}
deska.on('visibility', ({ visible }) => {
  clearInterval(timer)
  if (visible) start()
})
if (deska.visible) start()
else render()

1. deska.ready() responde con el panel, el tema, sus permisos y el idioma de la persona. Nada de Deska funciona antes.
2. deska.storage es donde perduran los datos: el sandbox no tiene localStorage ni cookies. Los valores son JSON, hasta 256 KB, compartidos por todas las copias del panel en la computadora. Las imágenes y otros archivos van en deska.files.
3. deska.setTitle muestra una línea bajo el nombre del panel en el lienzo: hasta 60 caracteres. null, un texto vacío o un título más largo se rechazan con invalid_args, nunca se recortan. Usa el nombre del propio panel, init.panel.name, para mostrar solo el nombre.
4. Toda llamada puede fallar con un código, como storage_full, permission_denied o not_focused. Responde a los que la persona puede resolver; los diez están en Códigos de error y límites.
5. deska.on('visibility') avisa cuando el panel queda fuera de la vista, plegado en un dock o detrás de la vista lejana. Ahí sigue corriendo, así que detén temporizadores y animaciones y ponte al día cuando vuelva a verse.

Un panel puede recargarse en cualquier momento: al pasar a un dock, al actualizarse, al reiniciar Deska. Guarda lo importante en el almacenamiento y reconstruye a partir de lo que devuelve deska.ready(). Cada método, con sus argumentos y errores, está en la referencia del SDK.

Abre la Biblioteca de paneles (Cmd/CtrlShiftE), ve a Comunidad, luego a Crear un panel, elige Cargar una carpeta y selecciona la carpeta donde está panel.json. Deska la revisa, te dice qué corregir, agrega el panel a tu escritorio y lo recarga cada vez que guardas un archivo. Cambia el tema de Deska para revisar los dos aspectos.

Para construir junto a tu editor sin Deska, el repositorio de ejemplos trae una herramienta de vista previa que sirve un panel con las mismas reglas y hace la parte de Deska en el SDK, con un registro de cada llamada:

git clone https://github.com/0xPasho/deska-panels-examples.git
cd deska-panels-examples
npm install
npm run preview -- starter                 # el tutorial terminado
npm run preview -- ruta/a/my-first-panel   # tu propia carpeta

• Abrir marcos por su cuenta, ejecutar workers ni cargar scripts desde internet. Para mostrar un reproductor de YouTube o la página de otro sitio, el panel se lo pide a Deska con deska.embed; los archivos de audio y video se reproducen desde los sitios que declaras.
• Conectarse a un sitio que no está en network, o a uno que no acepta solicitudes de cualquier origen (CORS). El origen del panel es opaco.
• Enviar un formulario a ningún lado, abrir ventanas emergentes ni llamar a alert(). Maneja tú el envío de un formulario y abre enlaces con deska.openUrl.
• Guardar un secreto. No hay un lugar seguro para un token, así que usa APIs públicas.
• Tomar el teclado por su cuenta. El foco solo se mueve cuando la persona usa el panel; pide atención con deska.notify.
• Cada regla, con qué hacer en su lugar, está en El sandbox.

Por ahora publicar está abierto a autores invitados. Antes de tu primer panel, cambia id, name y author por los tuyos, y cuéntanos qué estás construyendo en deska.dev/panels/apply.

Cuando aprueben tu cuenta, abre la página de la carpeta cargada en Crear un panel, pulsa Publicar, cuenta qué cambió y confirma. Sube version en cada entrega: una versión publicada nunca cambia. Las versiones, los permisos que se vuelven a preguntar y cómo ocultar un panel están en Publicar.