fluxplugin 1.0.3 → 1.0.4

package/dist/types/react/sidebar.d.ts

@@ -0,0 +1,42 @@
+import React, { type ReactNode } from "react";
+import type { MenuLocation } from "../core/index.js";
+interface SidebarCtx {
+    collapsed: boolean;
+    setCollapsed(v: boolean): void;
+    toggle(): void;
+    width: number;
+}
+/**
+ * Owns the collapsed/expanded state (persisted) and publishes the width as the CSS variable `--flux-sidebar-w`,
+ * which the shell's grid uses: `grid-cols-[var(--flux-sidebar-w,232px)_minmax(0,1fr)]`.
+ */
+export declare function SidebarProvider({ children, storageKey, expandedWidth, collapsedWidth }: {
+    children: ReactNode;
+    storageKey?: string;
+    expandedWidth?: number;
+    collapsedWidth?: number;
+}): React.ReactElement;
+export declare const useSidebar: () => SidebarCtx;
+export interface SidebarEntry {
+    id: string;
+    label: string;
+    path?: string;
+    command?: string;
+    /** Built-in icon name, an `{ d }` SVG path, or any React node. */
+    icon?: unknown;
+    badge?: string | number;
+    children?: SidebarEntry[];
+}
+export declare function renderIcon(icon: unknown, size?: number): ReactNode;
+/**
+ * Sidebar navigation: host entries (`top` / `bottom`) around the entries plugins add to the `sidebar` menu location.
+ * Supports icons, sub-menus (nested `children` or `parent` ids), collapsing to an icon rail (sub-menus become hover flyouts),
+ * and active highlighting. Labels of host entries can be translated through their `id` (`menu.<id>`).
+ */
+export declare function SidebarNav({ top, bottom, location, footer }: {
+    top?: SidebarEntry[];
+    bottom?: SidebarEntry[];
+    location?: MenuLocation;
+    footer?: ReactNode;
+}): React.ReactElement;
+export {};

package/dist/types/react/theme.d.ts

@@ -9,6 +9,21 @@ export interface ThemeDefinition {
     /** CSS custom properties, e.g. `{ "--flux-accent": "#e11d48", "--flux-bg": "#fff" }`. */
     tokens: Record<string, string>;
 }
+export interface FontDefinition {
+    id: string;
+    label: string;
+    /** CSS font-family stack. */
+    stack: string;
+    /** Optional @font-face CSS (use data: URLs or the plugin's asset URLs). */
+    css?: string;
+}
+export interface SettingsSection {
+    id: string;
+    title: string;
+    icon?: string;
+    order?: number;
+    component: React.ComponentType;
+}
 export interface SearchResult {
     id: string;
     title: string;
@@ -21,8 +36,26 @@ export interface SearchProvider {
     label: string;
     search: (query: string) => SearchResult[] | Promise<SearchResult[]>;
 }
-/** Declares the extension points used by the built-in theme and title-bar components. Call before `framework.start()`. */
+/** Declares the extension points used by the built-in components (theme, fonts, title bar, settings, i18n). Call before `framework.start()`. */
 export declare function declareHostPoints(framework: RendererFramework): void;
+export interface Appearance {
+    /** Accent colour (any CSS colour); undefined = the theme's own. */
+    accent?: string;
+    fontId: string;
+    /** Font family typed by the user (used before the chosen font). */
+    customFont: string;
+    /** Base text size in px (12–20). */
+    fontSize: number;
+    lineHeight: number;
+    density: "comfortable" | "compact";
+    translucency: boolean;
+    radius: "sharp" | "default" | "round";
+    reduceMotion: boolean;
+}
+export declare const DEFAULT_APPEARANCE: Appearance;
+export declare const BUILTIN_FONTS: FontDefinition[];
+/** Turns a font name typed by the user into a safe CSS family list (quotes added, no CSS injection possible). */
+export declare function sanitizeFontFamily(input: string): string;
 interface ThemeCtx {
     mode: ThemeMode;
     setMode(m: ThemeMode): void;
@@ -31,11 +64,15 @@ interface ThemeCtx {
     resolved: "light" | "dark";
     themes: ThemeDefinition[];
     toggle(): void;
+    appearance: Appearance;
+    setAppearance(patch: Partial<Appearance>): void;
+    resetAppearance(): void;
+    fonts: FontDefinition[];
 }
 /**
- * Light / dark / system modes plus themes contributed by plugins (extension point `theme`).
- * Applies `data-theme` and the theme's CSS variables on <html>, persists the choice, and reports the resolved
- * colours so the host can update the native window controls (`onResolved`).
+ * Light / dark / system modes, plugin themes, and the user's appearance preferences (accent, font, text size, density,
+ * translucency, corner radius, motion). Everything is applied as CSS variables / data attributes on <html> and persisted.
+ * `onResolved` reports the resolved colours so the host can colour the native window controls.
  */
 export declare function ThemeProvider({ children, storageKey, onResolved }: {
     children: ReactNode;
@@ -48,6 +85,7 @@ export declare function ThemeProvider({ children, storageKey, onResolved }: {
     }) => void;
 }): React.JSX.Element;
 export declare function useTheme(): ThemeCtx;
+export declare const useAppearance: () => Pick<ThemeCtx, "appearance" | "setAppearance" | "resetAppearance" | "fonts">;
 /** Sun/moon button; with plugin themes available it also offers a small picker. */
 export declare function ThemeSwitcher(): React.ReactElement;
 export {};

package/dist/types/react/ui.d.ts

@@ -0,0 +1,42 @@
+import React, { type ButtonHTMLAttributes, type ReactNode } from "react";
+import { type IconName } from "./icons.js";
+/** iOS/macOS-style toggle. */
+export declare function Switch({ checked, onChange, label, disabled }: {
+    checked: boolean;
+    onChange: (v: boolean) => void;
+    label?: string;
+    disabled?: boolean;
+}): React.ReactElement;
+/** Segmented control (like NSSegmentedControl / UISegmentedControl). */
+export declare function Segmented<T extends string>({ value, options, onChange, label }: {
+    value: T;
+    options: {
+        value: T;
+        label: ReactNode;
+    }[];
+    onChange: (v: T) => void;
+    label?: string;
+}): React.ReactElement;
+/** Inset grouped list ("Settings" look). */
+export declare function Group({ title, footer, children, className }: {
+    title?: ReactNode;
+    footer?: ReactNode;
+    children: ReactNode;
+    className?: string;
+}): React.ReactElement;
+export interface RowProps {
+    icon?: IconName | ReactNode;
+    iconColor?: string;
+    title: ReactNode;
+    subtitle?: ReactNode;
+    right?: ReactNode;
+    chevron?: boolean;
+    onClick?: () => void;
+    selected?: boolean;
+    "data-testid"?: string;
+}
+export declare function Row({ icon, iconColor, title, subtitle, right, chevron, onClick, selected, ...rest }: RowProps): React.ReactElement;
+export declare function Button({ variant, size, children, ...rest }: {
+    variant?: "primary" | "secondary" | "destructive" | "plain";
+    size?: "sm" | "md" | "lg";
+} & ButtonHTMLAttributes<HTMLButtonElement>): React.ReactElement;

package/docs/CUSTOMIZING.md

@@ -251,6 +251,62 @@ Authors work in TypeScript (`src/`), but what is **installed and shipped** is on
 through the Plugin Manager / registries copy *only* these files — never `src/`, `.ts/.tsx`, sourcemaps, `node_modules`, configs.
 Add `--sign-key` to sign the package (ed25519) and set `trustedKeys` + `requireSignature` in `framework.ts` to refuse the rest.
 
+## 9. Settings, languages and fonts
+
+**Settings screen** (`/settings/:section`, macOS "System Settings" look). Sections are contributed to the `settings` extension point:
+```ts
+extensions: [{ point: "settings", contribution: { sections: [{ id: "billing", title: "Billing", icon: "info", order: 30, component: BillingSettings }] } }]
+```
+The app ships two plugins that do exactly this: **Appearance** (mode, themes, accent, font, text size, spacing, corners, translucency,
+reduced motion) and **Language**. Remove or replace them freely: they are ordinary plugins in `plugins/`.
+
+**Fonts** — users pick a family, type any installed font name, and set size / line spacing; plugins add fonts:
+`extensions: [{ point: "font", contribution: { fonts: [{ id: "brand", label: "Brand", stack: '"Brand Sans", sans-serif', css: "@font-face{…}" }] } }]`.
+In code: `const { appearance, setAppearance } = useAppearance()` (accent, fontId, customFont, fontSize, lineHeight, density, radius, translucency, reduceMotion).
+
+**Languages** — `useT()("key", "English fallback")` everywhere; plugins contribute languages and translations to the `i18n` point
+(`{ languages: [{ code: "ar", label: "Arabic", nativeLabel: "العربية", rtl: true }] }`, `{ messages: [{ locale: "ar", messages: {…} }] }`).
+Missing keys fall back to English. Host entries are translated with `menu.<id>` keys (`menu.dashboard`).
+
+## 10. Sidebar: icons, collapse, sub-menus
+The sidebar collapses to an icon rail (button at the bottom, `Ctrl/Cmd+B`; state persisted; sub-menus become hover flyouts).
+Plugins add entries and sub-menus:
+```ts
+routes: [{ path: "/reports", component: Reports, meta: { title: "Reports", menu: { label: "Reports", icon: "grid", order: 20 } } },
+         { path: "/reports/sales", component: Sales, meta: { menu: { label: "Sales", parent: "route:/reports" } } }]   // parent = menu id
+menus: [{ id: "tools", location: "sidebar", label: "Tools", icon: { d: "M…svg path…" }, children: [{ id: "t1", label: "Sync", path: "/sync" }] }]
+```
+`icon` is a built-in name (`home`, `plug`, `settings`, `palette`…), `{ d: "<svg path>" }` or any React node. Unknown `parent` ids fall back to the top level.
+The shell uses `grid-cols-[var(--flux-sidebar-w,232px)_minmax(0,1fr)]` so the content area follows the collapse.
+
+## 11. Images and video — any source
+```tsx
+<Img src="https://…" />   <Img src="data:image/png;base64,…" />   <Img src={rawBase64} />   <Img src={blobUrl} />   <Img src={file /* Blob | File | Uint8Array */} />
+<Img src="C:\\Users\\me\\a.png" />   <Img src="/home/me/a.png" />   <Img src="assets/shot.png" base={pluginAssetBase} />
+```
+Allowed: http(s), `data:image/*`, raw base64 (type detected from the bytes), `blob:`, `file:`/local paths, relative paths (with `base`), Blob/File/ArrayBuffer.
+Rejected: `javascript:` and other schemes. Failing images show a placeholder. Markdown images use the same rules.
+`<VideoPlayer video={parseVideo(url)} />`: **YouTube, Vimeo, Dailymotion, Loom, Streamable** → sandboxed iframe; **mp4 / webm / ogg / mov** (https, or a file inside the plugin such as
+`"video": "./assets/tour.mp4"`) → native HTML5 player with seeking; anything else → a link. Your CSP must list the iframe hosts (the generated `index.html` does).
+
+## 12. Build, ship, export
+```bash
+npm run build              # app + all plugins (no sourcemaps)
+npm run dist               # installer/executable for this OS (electron-builder): npm run dist -- --win --mac --linux
+npm run dist -- --unpacked # just the unpacked app folder (fast check)
+npm run export:web         # static website in ./website (renderer + plugin files + bootstrap.json); serve with any static host
+npm run plugins:package    # every plugin → release/plugins/*.tgz (runtime files only)
+```
+Bundled plugins are staged **runtime-only** (`.flux-build/plugins`: `plugin.json`, `dist/`, `assets/`, README) — no `src/`, no `.ts`, no `.map`.
+User-installed plugins live in the app's data folder; `deleteAppDataOnUninstall: true` (Windows) removes them with the app. macOS has no uninstaller:
+drag-to-Trash leaves `~/Library/Application Support/<app>`. The static export runs only the browser side (main-process plugin code and IPC are unavailable).
+
+## 13. Plugins are normal projects
+`npm create fluxplugin-plugin my-plugin` (or `npx fluxplugin plugin new my-plugin --standalone`) creates a React + TypeScript project with **its own
+`package.json` and libraries**. Install anything (`npm i chart.js react-markdown …`): it is bundled into `dist/`, so the host app needs nothing.
+Only `react`, `react-dom`, `fluxplugin` and `fluxplugin/react` are shared with the host. CSS imported by the plugin or its libraries becomes `dist/renderer.css`
+(auto-listed in the manifest); images and fonts are inlined. `npm run dev:host` rebuilds on save and syncs the runtime files into a running host app, which hot-reloads them.
+
 ## 9. Plugin stores (marketplace)
 
 Where *Plugins → Available* looks is your choice: the default GitHub store, your own catalog (HTTP/GitHub/local), or code of your own.

package/docs/STORE.md

@@ -86,6 +86,25 @@ jobs:
 ```
 (The built-in token can create releases but not edit topics; add the topic `fluxplugin-plugin` once in the repo settings.)
 
+## B2. A catalog repository (folders + one JSON) — GitHub, any host, or an API
+
+Besides the topic store, a store can be **a repository of plugin folders and a single JSON that holds all their metadata**:
+```
+acme/plugin-store
+├─ plugins/
+│  ├─ weather/   plugin.json · dist/ · assets/ · README.md   (src/ may be there; it is never listed or downloaded)
+│  └─ notes/     …
+└─ index.json    ← generated: id, name, version, description, permissions, icon, screenshots, video, readme, files + sha256 of every file
+```
+```bash
+npx fluxplugin store build .          # builds index.json from plugins/*/plugin.json (commit it; run it in CI on every change)
+```
+Point the app at it: `{ "type": "github", "repo": "acme/plugin-store" }` (reads `index.json` from the repo), **or** any link that returns the JSON:
+`{ "type": "json", "url": "https://api.acme.com/plugins" }` / `{ "type": "http", "url": "https://acme.github.io/store/index.json" }`.
+Entries are either packages (`url` + `sha256`) or folders (`folder` + `files` + `hashes`); relative URLs resolve against the JSON. The app asks the store first, then
+compares each entry with what is installed locally (*Installed / Update / Get*). Every downloaded file is verified against its hash.
+`fluxplugin init my-app --store github:acme/plugin-store` writes this into `fluxplugin.config.json`.
+
 ## C. Install from the store
 
 * **In an app**: *Plugins → Available* lists plugins with their permissions; **Install**. Enabled automatically (or after the user approves permissions when your app uses `requireApproval`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fluxplugin",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Plugin architecture for Electron + React + TypeScript. Build apps that others can extend: routes, menus, commands, UI slots, IPC, hooks, permissions — with a CLI.",
   "license": "MIT",
   "keywords": [