0.1.0-beta.10

@diamonddigitaldev/electron-kit | Beta Preview (v0.1.0-beta.10)

Important

A beta: the API can still change between 0.x versions. It's published under npm's next tag.

Cards for a list of files or transfers, with selection and a bulk bar, plus a stepped slider, a switch whose help follows it, and busy buttons. Every new piece is additive: an app on 0.1.0-beta.9 runs on it unchanged. The one thing that can break is a test that matches kit.format.summarise()'s old wording: see Changed.

npm install @diamonddigitaldev/electron-kit@next

New

• kit.ui.card({ icon, name, onConfigure, onRemove, route }) → { element, update(state) }: a card for one item of work. Its head (a selection box, the kind's glyph, the name, Advanced Options and Remove), a meta line, a settings line, a route row ("To", or "MP4 →", then the app's own control), a status line whose dot takes one of six tones (running pulses, still under reduced motion), a thin progress bar, the app's own rows, and the card's buttons, rebuilt only when they change. update() takes the whole state each time; locked disables the card's controls, and canRemove keeps Remove while the rest is locked. Every button on a card is one size.
• kit.ui.cardGrid(container, { view, onSelect }): the cards side by side, in the order added, with a file manager's selection: a click selects one, Ctrl/Cmd toggles, Shift selects a range, a card's box toggles just its card, the empty space clears; Ctrl+A and Escape in its view. add, remove, cards, selection, select, selectAll, clear. The rules are also public as kit.ui.cardGrid.resolveSelection() and pruneSelection(), for a list that isn't cards.
• kit.ui.bulkBar(grid, { noun, target, actions }) → { element, refresh() }: the select-all box (half ticked when some are), "Select all" / "N selected", the app's target select labelled "… all to" / "… selected to" with its note, the app's actions (always, or only with a selection), and Deselect.
• kit.ui.busy(button, label) → restore(): the button disabled, with a small spinner before "Pausing…" or whatever it's doing; restore() puts it back.
• kit.ui.switchField({ id, label, checked, help: { on, off }, onChange }) → { element, input, set(checked) }: a switch with one help line that says what the state it's in does, and changes with it.
• kit.ui.stepSlider({ id, label, min, max, value, valueText, help, onChange }) → { element, input, set(n) }: a choice of a few whole numbers (up to 10), a node per value the knob snaps to, filled in the accent up to the knob. A native range underneath, so the keyboard and screen readers work as they always do.
• progress().set(percent, { paused: true }): a paused bar keeps its value, faded and still.

Changed

• kit.format.summarise()'s wording: its clauses are joined with " · " in Title Case, the noun on the first count: "3 Files Converted · 1 Failed · 1 Skipped" (was "3 files converted, 1 failed, 1 skipped"). "Nothing converted" stays a sentence. The signature is the same, but an app's tests that match the old wording need changing.
• Settings > Update: Check for Updates shows "Checking…" with a spinner while a check runs, however it was started, and Restart Now "Restarting…" while it installs. "Download updates automatically" is now a switchField() (same ids and words).
• Every range's knob is in the accent, with the house's focus ring instead of Bootstrap's blue glow.
• Settings' tab bar sits under the selected tab's word, and the update dot no longer moves it.
• Outline buttons on a card or the bulk bar are filled with the page's colour, and an outline danger button's text on the dark theme is the theme's danger text colour, so both keep 4.5:1.

Docs

• Page Components: Cards, the Card Grid, the Bulk Bar, the Switch, the Stepped Slider, summarise() under Format, and the new Copy Rules (a capital after a colon; Title Case between bullets unless an item is a sentence; names and addresses never recased).
• The Shell, Settings and Credits: the Update tab's busy buttons and the tab bar.

The docs are in the repository: start at docs/README.md.

Found something wrong? Open an issue.

0.1.0-beta.9

@diamonddigitaldev/electron-kit | Beta Preview (v0.1.0-beta.9)

Important

A beta: the API can still change between 0.x versions. It's published under npm's next tag.

The Windows installer gets its own look and clearer pages: a welcome page, file types as a tree, a page for the shortcuts, and a sidebar made from the app's icon and accent. The uninstaller can remove the app's settings and logs. An app on 0.1.0-beta.8 runs on it without a change to its config() call, as long as its build.linux.icon is a PNG and it has src/styles/accent.css (or gives sidebar.colour): see Changed.

npm install @diamonddigitaldev/electron-kit@next

New

• A welcome page opens the installer: "Welcome to Setup", the version, and what it'll ask (who it's for, then the files it opens and its shortcuts, where the app has them). An update skips it.
• Choose File Types is a tree: a branch per file type group, expanded, with a box per extension, and the Open With line above it. It scrolls, so the page's column limit, Tick All and Untick All are gone. An update skips it.
• Shortcuts & Right-Click Menu, a page of its own: "Add a desktop shortcut", "Add a Start menu shortcut" and the right-click entry, all ticked (an app without an entry gets "Shortcuts"). The choices are kept, so an update never brings back a shortcut that was unticked, and never makes one the person deleted. Silently, /NODESKTOPSHORTCUT (or electron-builder's --no-desktop-shortcut) and /NOSTARTMENUSHORTCUT, beside /FILETYPES= and /NOCONTEXTMENU.
• "Also remove settings and logs", an unticked box on the uninstaller's welcome page. Ticked, or with --delete-app-data, the app's data folders go too, retrying for a few seconds if Windows still holds one. A silent uninstall or an update keeps them.
• The sidebar on the welcome and finish pages, the installer's and the uninstaller's, is made from the app's icon on a gradient in its accent, instead of electron-builder's stock picture. sidebar: { colour: "logo" } takes the icon's own main colour instead, and "#rrggbb" any colour. The kit makes it itself, with no image library.

Changed

• build.linux.icon must be the app's icon as a PNG (512 × 512, 8-bit, not interlaced): the sidebar is made from it. config() says so if it isn't.
• The sidebar is in --accent from src/styles/accent.css unless sidebar.colour says otherwise; without either, config() says what to give.
• config() now also sets, and refuses from an app, nsis.installerSidebar, nsis.uninstallerSidebar, nsis.deleteAppDataOnUninstall and nsis.removeDefaultUninstallWelcomePage. A file type group's name can't start with - or !.
• config() writes the installer's include and the sidebar to a temp folder of the user's own, so one another user made in a shared /tmp never stops a build.
• electron-updater's own lines go to the kit's log, redacted, at debug, instead of to the console: its error dump (the URL with its query, the response headers, the stack) no longer reaches a terminal. The kit's one-line warning for a failed check, download or install is still logged as before.

Known

• Without a Start menu shortcut, Windows doesn't deliver an app's notifications, though Electron still reports them shown. An app that relies on its notifications should say so near the box.

Docs

• Building: the installer's pages, the switches, the sidebar and build.linux.icon, the uninstaller's box, the notifications note.
• Updates: electron-updater's lines in the log.

The docs are in the repository: start at docs/README.md.

Found something wrong? Open an issue.

0.1.0-beta.8

@diamonddigitaldev/electron-kit | Beta Preview (v0.1.0-beta.8)

Important

A beta: the API can still change between 0.x versions. It's published under npm's next tag.

Settings > Update never shows an empty status line, and a launch never checks for updates twice. An app on 0.1.0-beta.7 runs on it without a change.

npm install @diamonddigitaldev/electron-kit@next

Changed

• Before the first check, the Update tab says so. For the 5 seconds before the launch check, the status line was empty. It now says "Updates haven't been checked yet."
• Settings > Update opened before the launch check runs it at once, so someone who goes straight there sees where the updates stand rather than waiting for the timer. The status from getUpdateStatus() and onUpdateStatus() gains pending, true while the launch check waits.

Fixed

• A check run before the launch check takes its place. Check for Updates pressed in the first 5 seconds was followed by a second check, and the status line went back to "Checking for updates…" after it had said "You're up to date."

Docs

• Updates: the launch check run by the Update tab, and pending.

The docs are in the repository: start at docs/README.md.

Found something wrong? Open an issue.

0.1.0-beta.7

@diamonddigitaldev/electron-kit | Beta Preview (v0.1.0-beta.7)

Important

A beta: the API can still change between 0.x versions. It's published under npm's next tag.

An app can keep a launch it handles itself out of files:opened, and the log never names the files an app is opened with. The log kept on disk has a size limit. An app on 0.1.0-beta.6 runs on it without a change.

npm install @diamonddigitaldev/electron-kit@next

New

• start({ files: { except: ["--upload"] } }): a launch, first or second, with one of those switches is the app's to handle, so none of its files reach the page as files:opened. Dropgate's "Share with Dropgate" (the file, then --upload) uploads in the background instead. A second launch still brings the main window back. files: true is as before.

Changed

• The log says how many files the app was opened with, never which. The line kept the files' names after redaction, and a file's name can say as much about a person as its folder.
• The memory log's debug.log, kept on disk, holds at most twice the lines kept in memory after the banner. Past that, it's written again from the banner and the run's last lines, so a long run can't grow it without end.

Docs

• The Main Process: One Instance and Files (files.except), and The Log (the file's limit).

The docs are in the repository: start at docs/README.md.

Found something wrong? Open an issue.

0.1.0-beta.6

@diamonddigitaldev/electron-kit | Beta Preview (v0.1.0-beta.6)

Important

A beta: the API can still change between 0.x versions. It's published under npm's next tag.

The installer asks before it claims a file type or adds a right-click entry, and asks who it's for. On Linux, an app is in Open With for the files it opens, and the dock knows its window. An app on 0.1.0-beta.5 runs on it without a change, but its build config should move to the kit's config() to get either: see below.

npm install @diamonddigitaldev/electron-kit@next

New

• config(), from @diamonddigitaldev/electron-kit/builder: an app's whole electron-builder config, on the kit's base, from its own options, the files it opens and its right-click entry. It goes in electron-builder.cjs, beside package.json, and package.json's build goes (electron-builder would read it first). .cjs, never .js: on Windows, electron-builder typed in a folder holding electron-builder.js runs that file with Windows Script Host instead.

const { config } = require("@diamonddigitaldev/electron-kit/builder");

module.exports = config(require("./package.json"), {
    build: { appId, productName, publish, win, linux: { icon, category: "AudioVideo" }, nsis, ... },
    fileTypes: [{ name: "Audio File", ext: ["mp3", "wav"] }, { name: "Video File", ext: ["mp4"] }],
    contextMenu: { label: "Convert with App", folders: true },
});

• The asking installer (Windows). It asks who it's for: "Only for me" by default, with no administrator prompt, or everyone. An install for everyone already there is upgraded in place, never joined by a second copy. Then a box for each file type, in the app's groups, all ticked, and one for the right-click entry. A ticked type puts the app in Open With and in Settings > Apps > Default apps, and becomes the default only where no app has been chosen; an unticked one gets nothing. The choices are kept, so an update never adds back what was unticked. Uninstalling takes away everything the installer added. Silently, /FILETYPES=all, none or a list, and /NOCONTEXTMENU.
• Linux's desktop entry. The .desktop file lists the file types' MIME types, so the app is in the file manager's Open With, and gets every selected file. It's named for the app's appId, which Electron gives the running window, so the dock shows the app's own icon. allFiles: true, for an app that takes any file, puts it in Open With for every file.
• assertBuildExtendsKit() takes the config itself: assertBuildExtendsKit(require("../electron-builder.cjs")).

Changed

• config() never sets electron-builder's fileAssociations, which claim every type on Windows without asking, and refuses them, with an app's own nsis.include (its installer.nsh), perMachine and oneClick: the kit's installer asks instead. build.linux.category is needed.

Docs

• Building: config(), the asking installer, the files an app opens on Linux, and the .deb and .rpm updating themselves (after a password prompt).
• Getting Started and Testing an App: the builder export, and the build config's check.

The docs are in the repository: start at docs/README.md.

Found something wrong? Open an issue.

0.1.0-beta.5

@diamonddigitaldev/electron-kit | Beta Preview (v0.1.0-beta.5)

Important

A beta: the API can still change between 0.x versions. It's published under npm's next tag.

Windows shows an app's notifications and groups its windows under its pinned icon, and no ID of the install is left on disk. An app on 0.1.0-beta.4 takes it without a change, but should pass start({ appId }): see below.

npm install @diamonddigitaldev/electron-kit@next

New

• start({ appId }). Windows' app user model ID is now the ID an app passes, which should be its package.json's build.appId. The installer gives the Start menu shortcut that ID, and Windows shows an app's notifications, and groups its windows under its pinned taskbar icon, only when the two match. It's checked as a dotted ID, and set with singleInstance: false too. Pass it: without appId, the ID is the app's name, as before, which matches nothing the installer made.

const kit = require("@diamonddigitaldev/electron-kit/main").start({
    appId: "com.diamonddigitaldev.app", // package.json's build.appId
    // …
});

Privacy

• A .updaterId an earlier version left is deleted. 0.1.0-beta.4 stopped electron-updater making an ID of the install, but left a .updaterId an earlier version had written, unread. Now the updater deletes it as it starts, in a packaged app only, and logs that it did; a failure is one warning. It's still never read or sent.

Docs

• The Main Process: appId, and why it should match build.appId.
• Getting Started: passes one.
• Updates: the ID of the install, and the old file deleted.

The docs are in the repository: start at docs/README.md.

Found something wrong? Open an issue.

0.1.0-beta.4

@diamonddigitaldev/electron-kit | Beta Preview (v0.1.0-beta.4)

Important

A beta: the API can still change between 0.x versions. It's published under npm's next tag.

No ID of the install on disk, and Settings > Update finishes the job: Restart Now, the download's progress, and a dot that's easier to notice. An app on 0.1.0-beta.3 takes it without a change; busy is optional.

npm install @diamonddigitaldev/electron-kit@next

Privacy

• No ID of the install is made, kept or sent. Left to itself, electron-updater makes a random ID on its first update check and writes it to the app's userData folder (.updaterId), for staged rollouts. The kit already sent a fixed ID in its place; now it gives electron-updater that fixed ID before the first check, so no ID is made and no file is written. Every install is offered every release (no app on the kit uses staged rollouts). A .updaterId an earlier version wrote is left where it is, and never read or sent.

New

• Restart Now. Once an update has downloaded, Settings > Update shows Restart Now where Check for Updates was. It installs the update at once and starts the new version, through a new shared channel, update:install (kitAPI.installUpdate()), checked like every other.
• mountShell({ busy }). A function that returns what the app is busy with ("A conversion is running."), or null. With a reason, Restart Now asks first, in the kit's prompt, with the focus on Cancel. Without busy, it restarts at once.
• The download's progress. While an update downloads, a bar in the app's accent shows under the status line, and it's gone the moment the download finishes or fails.

Changed

• The update dot breathes, slowly, wherever it shows, and stays still when the system asks for less motion. On the nav rail it's smaller (6px), and on the collapsed rail it sits in the Settings item's top-right corner.

Docs

• Updates: the ID of the install, and installing at once.
• The Shell, Settings and Credits: Restart Now, busy, the bar and the dot.
• IPC: update:install.

The docs are in the repository: start at docs/README.md.

Found something wrong? Open an issue.

0.1.0-beta.3

@diamonddigitaldev/electron-kit | Beta Preview (v0.1.0-beta.3)

Important

A beta: the API can still change between 0.x versions. It's published under npm's next tag.

What an app needs to keep nothing it wasn't asked to, and to run a window without the kit's bridge. Everything here is new and changes nothing an app already uses: an app on 0.1.0-beta.2 takes it without a change.

npm install @diamonddigitaldev/electron-kit@next

New

• The memory log. start({ log: "memory" }) keeps the run's last lines in memory (1000, or { mode: "memory", lines }), redacted as the file log is, and writes nothing to disk. It adds a setting, keepLogOnDisk, off by default, for a switch the app shows itself: turned on, the run so far is written to debug.log and each line after it added; turned off, or off at launch, debug.log is deleted. kit.log.lines() gives the last lines in every mode, so an app can copy or save them.
• Isolated sessions. kit.sessions.isolated(name) gives a session without the kit's bridge, for a window that handles data from the network or shows a page that isn't the app's: a partition of its own, in memory unless { persist: true }, with no spell-check dictionaries, and every permission refused. kit.ipc.handle(channel, handler, { session }) answers the app's own page in that session only, and refuses the main window's.
• An allowlist for links. start({ openExternal: { allow: [...] } }) narrows shell:open-external to the sites listed, matched as URLs (the same scheme, host and port, and a path inside the entry's), never as text, so https://diamonddigital.dev doesn't let https://diamonddigital.dev.example.com through. The links the kit shows from the app's own config (the Credits tab's, and the repository's releases) are always allowed.
• The outside-lookup check, for an app's own tests. netLogSwitches(), outsideLookups(), proxyLookups() and assertNoOutsideLookups() in electron-kit/testing read Chromium's net log once the app has quit, and fail on any name looked up beyond the machine, or any search for a proxy. The kit's own tests check every launch of its demo this way, on Windows and Linux.

Docs

• New pages: Testing an App, and sections on the memory log and isolated sessions in The Main Process, and on the allowlist in IPC.
• How spell checking is kept from downloading dictionaries, on every session.

The docs are in the repository: start at docs/README.md.

Found something wrong? Open an issue.

0.1.0-beta.2

@diamonddigitaldev/electron-kit | Beta Preview (v0.1.0-beta.2)

Important

A beta: the API can still change between 0.x versions. It's published under npm's next tag.

The same kit as 0.1.0-beta.1, and the first version published with provenance. 0.1.0-beta.1 was published by hand, because npm only lets a trusted publisher be set up for a package that's already there. From this version on, each one is published by GitHub Actions through npm's trusted publishing, with provenance, so anyone can check which commit and workflow built it, and nothing goes live until a maintainer approves it with two-factor authentication.

npm install @diamonddigitaldev/electron-kit@next

Changes

• Nothing in the package's code. Its files are as 0.1.0-beta.1's, apart from package.json's version and the README's version badge.
• The release workflow (release.yml): a published GitHub release is checked against the version and branch, runs every test on Ubuntu and Windows, and stages the package on npm with provenance. Dependabot keeps the kit's and the demo's dependencies current.
• The docs say how releases work (Development).
• CI runs the Electron tests one at a time. The public repository's larger runners started two at once, which the shared virtual display on Linux can't take.

The docs are in the repository: start at docs/README.md.

Found something wrong? Open an issue.

0.1.0-beta.1

@diamonddigitaldev/electron-kit | Beta Preview (v0.1.0-beta.1)

Important

This is the first public version, and a beta: the API can still change between 0.x versions. It's published under npm's next tag.

The shared design system for Diamond Digital Development's Electron apps: one package that holds what the apps share, so a fix to shared UI or behaviour is made once, here, and each app takes it with a version bump. Diamond File Converter 2.0 is the first app built on it.

npm install @diamonddigitaldev/electron-kit@next

What's in it

• Main-process behaviour from one call, start(): a sandboxed, context-isolated main window that keeps its size and position, one instance and the files an app is opened with, the settings and their migration, a log redacted to file names, the house menu, and an updater with Stable, Beta and Alpha channels.
• A shared preload, window.kitAPI, registered on the app's session, that answers the app's own page only, and kit.ipc.handle(), the same check for an app's own channels.
• Page components and CSS on Bootstrap 5.3: the nav rail, the Settings view with its Update and Credits tabs, toasts, prompts, drop zones, progress and the action bar, in each app's accent, meeting WCAG 2.2 AA in both themes.
• An electron-builder base config: an NSIS installer on Windows; AppImage, .deb and .rpm on Linux.
• Test helpers for an app's own tests: the accent's contrast, the menu's shortcuts, the build config.

Requires Electron 44 or later and Node.js 24 or later. Windows and Linux.

The docs are in the repository: start at docs/README.md.

Note

This version was published to npm by hand, since npm only lets a trusted publisher be set up for a package that's already there. From the next version on, each is published by GitHub Actions with provenance, and only after a maintainer approves it with two-factor authentication.

Found something wrong? Open an issue.