ais6-app 0.1.0 → 0.2.0

package/template/src/main.tsx

@@ -0,0 +1,105 @@
+import { render } from "preact";
+import {
+  connect,
+  exportFile,
+  onLanguage,
+  onLifecycle,
+  onMenuCommand,
+  pushMenuState,
+  readState,
+  setTitle,
+  writeState,
+} from "./bridge/bridge.ts";
+import { type Language, translate } from "./strings/index.ts";
+import { App } from "./ui/App.tsx";
+import "./styles/app.css";
+
+const NOTE_KEY = "note";
+// Menu actions in app.manifest.json; the app id in front keeps them apart from the desk's own.
+const CLEAR = "__APP_ID__-clear";
+const EXPORT = "__APP_ID__-export";
+const SAVE_DELAY_MS = 400;
+
+async function main(): Promise<void> {
+  const root = document.getElementById("app");
+  if (!root) return;
+  const client = await connect();
+  let language: Language = client.welcome.language === "zh" ? "zh" : "en";
+  const stored = await readState(client, NOTE_KEY);
+  let note = typeof stored === "string" ? stored : "";
+  let saved = true;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  const save = async () => {
+    clearTimeout(timer);
+    timer = undefined;
+    saved = await writeState(client, NOTE_KEY, note);
+    draw();
+  };
+  const menus = () =>
+    pushMenuState(client, {
+      available: { [CLEAR]: note.length > 0, [EXPORT]: note.length > 0, "close-active-window": true },
+      checked: {},
+    });
+  const draw = () => {
+    document.documentElement.lang = language === "zh" ? "zh-CN" : "en";
+    render(
+      <App
+        language={language}
+        note={note}
+        saved={saved}
+        standalone={client.standalone}
+        onInput={(text) => {
+          note = text;
+          saved = false;
+          clearTimeout(timer);
+          timer = setTimeout(save, SAVE_DELAY_MS);
+          menus();
+          draw();
+        }}
+      />,
+      root,
+    );
+  };
+
+  onMenuCommand(client, (action) => {
+    if (action === CLEAR) {
+      note = "";
+      void save();
+      menus();
+      return true;
+    }
+    if (action === EXPORT) {
+      void exportFile(
+        client,
+        `${translate(language, "app_title")}.txt`,
+        "text/plain",
+        new Blob([note], { type: "text/plain" }),
+      );
+      return true;
+    }
+    return false;
+  });
+  // The desk asks before it closes or hides the window: finish the pending save first.
+  onLifecycle(client, {
+    suspend: async () => {
+      if (timer !== undefined) await save();
+    },
+    resume: () => draw(),
+    dispose: () => clearTimeout(timer),
+  });
+  onLanguage(client, (next) => {
+    language = next;
+    setTitle(client, translate(language, "app_title"));
+    draw();
+  });
+  // Lets the desk keep a picture of the window for the Dock and the window list.
+  client.enableSnapshots({ producer: "dom", target: root });
+  setTitle(client, translate(language, "app_title"));
+  menus();
+  draw();
+  // First paint is done: the desk stops its loading state and takes the first picture.
+  client.ready();
+}
+
+void main();

package/template/src/strings/en.ts

@@ -0,0 +1,15 @@
+// English strings. The key type of the app comes from this table, so a
+// misspelled key does not compile. Window titles and menu labels also live in
+// app.manifest.json, because the desk draws those before the frame loads.
+export const en = {
+  app_title: "__NAME__",
+  note_label: "Note",
+  note_placeholder: "Write anything. It is kept when the window closes.",
+  word_count: "{count} words",
+  saved: "Saved",
+  standalone: "Running on its own page: notes stay in this browser.",
+  clear: "Clear",
+  export_text: "Export as Text",
+} as const;
+
+export type StringKey = keyof typeof en;

package/template/src/strings/index.ts

@@ -0,0 +1,23 @@
+import { en, type StringKey } from "./en.ts";
+import { zh } from "./zh.ts";
+
+export type { StringKey };
+export type Language = "en" | "zh";
+
+const tables: Record<Language, Record<StringKey, string>> = { en, zh };
+
+/** The translated string, with {name} placeholders filled from `values`. */
+export function translate(language: Language, key: StringKey, values: Record<string, string | number> = {}): string {
+  const text = tables[language][key];
+  return text.replace(/\{(\w+)\}/g, (match, name: string) => (name in values ? String(values[name]) : match));
+}
+
+/** Words in Latin text, characters in Chinese text: what a writer means by length. */
+export function countWords(text: string): number {
+  const han = text.match(/\p{Script=Han}/gu)?.length ?? 0;
+  const latin = text
+    .replace(/\p{Script=Han}/gu, " ")
+    .split(/\s+/)
+    .filter(Boolean).length;
+  return han + latin;
+}

package/template/src/strings/zh.ts

@@ -0,0 +1,13 @@
+import type { StringKey } from "./en.ts";
+
+// 简体中文。键与英文表一一对应；缺一个键就编译不过。
+export const zh: Record<StringKey, string> = {
+  app_title: "__NAME_ZH__",
+  note_label: "便条",
+  note_placeholder: "随便写点什么。关掉窗口也会留着。",
+  word_count: "{count} 字",
+  saved: "已保存",
+  standalone: "正在独立页面上运行：便条只存在这个浏览器里。",
+  clear: "清空",
+  export_text: "导出为文本",
+};

package/template/src/styles/app.css

@@ -0,0 +1,42 @@
+/* The app's own layout. Colours, fonts and controls come from the kit
+   (kit.css and the --kit-* tokens the desk sends for its appearance), so the
+   window follows Classic, Platinum, Liquid Glass and the rest without an
+   appearance selector here. */
+
+html,
+body,
+#app {
+  height: 100%;
+  margin: 0;
+}
+
+.app-pane {
+  display: grid;
+  grid-template-rows: auto 1fr auto;
+  gap: 6px;
+  height: 100%;
+  box-sizing: border-box;
+  padding: 10px;
+}
+
+.app-label {
+  font: var(--kit-control-size, 13px) var(--kit-ui-font, system-ui, sans-serif);
+}
+
+.app-note {
+  resize: none;
+  min-height: 0;
+  width: 100%;
+  box-sizing: border-box;
+  font-family: var(--kit-text-font, Geneva, Verdana, sans-serif);
+}
+
+.app-status {
+  display: flex;
+  justify-content: space-between;
+  gap: 12px;
+}
+
+.app-status > :first-child {
+  white-space: nowrap;
+}

package/template/src/ui/App.tsx

@@ -0,0 +1,34 @@
+import type { Language } from "../strings/index.ts";
+import { countWords, translate } from "../strings/index.ts";
+
+interface Props {
+  readonly language: Language;
+  readonly note: string;
+  readonly saved: boolean;
+  readonly standalone: boolean;
+  readonly onInput: (text: string) => void;
+}
+
+/** The whole window: one field and a status bar, drawn with the kit's classes. */
+export function App({ language, note, saved, standalone, onInput }: Props) {
+  const t = (key: Parameters<typeof translate>[1], values?: Record<string, string | number>) =>
+    translate(language, key, values);
+  return (
+    <div class="kit-pane app-pane">
+      <label class="app-label" for="note">
+        {t("note_label")}
+      </label>
+      <textarea
+        id="note"
+        class="kit-field app-note"
+        value={note}
+        placeholder={t("note_placeholder")}
+        onInput={(event) => onInput(event.currentTarget.value)}
+      />
+      <div class="kit-status-bar app-status" aria-live="polite">
+        <span>{t("word_count", { count: countWords(note) })}</span>
+        <span>{standalone ? t("standalone") : saved ? t("saved") : ""}</span>
+      </div>
+    </div>
+  );
+}

package/template/tests/unit/strings.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, expectTypeOf, it } from "vitest";
+import manifest from "../../public/app.manifest.json";
+import { APP_VERSION } from "../../src/bridge/bridge.ts";
+import { en } from "../../src/strings/en.ts";
+import { countWords, type StringKey, translate } from "../../src/strings/index.ts";
+import { zh } from "../../src/strings/zh.ts";
+
+describe("strings", () => {
+  it("rejects a misspelled key at compile time", () => {
+    expectTypeOf<"app_title">().toMatchTypeOf<StringKey>();
+    // @ts-expect-error -- not a key of the English table.
+    const misspelled: StringKey = "app_titel";
+    expect(misspelled).toBe("app_titel");
+  });
+
+  it("has every English key in Chinese", () => {
+    expect(Object.keys(zh).sort()).toEqual(Object.keys(en).sort());
+  });
+
+  it("names the window the way the manifest does, in both languages", () => {
+    expect(translate("en", "app_title")).toBe(manifest.strings.en.app_title);
+    expect(translate("zh", "app_title")).toBe(manifest.strings.zh.app_title);
+  });
+
+  it("counts Chinese by character and English by word", () => {
+    expect(countWords("hello there")).toBe(2);
+    expect(countWords("你好 world")).toBe(3);
+    expect(translate("en", "word_count", { count: 3 })).toBe("3 words");
+  });
+});
+
+describe("versions", () => {
+  it("connects with the manifest's version, or the desk refuses the hello", () => {
+    expect(APP_VERSION).toBe(manifest.version);
+  });
+});

package/template/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "jsxImportSource": "preact",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "resolveJsonModule": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src", "tests", "vite.config.ts", "vitest.config.ts"]
+}

package/template/vite.config.ts

@@ -0,0 +1,9 @@
+import preact from "@preact/preset-vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  // The build is served from /apps/__APP_ID__/ inside the desk and from any folder on its own.
+  base: "./",
+  plugins: [preact()],
+  build: { outDir: "dist", emptyOutDir: true },
+});

package/template/vitest.config.ts

@@ -0,0 +1,5 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: { include: ["tests/unit/**/*.test.ts"], environment: "node" },
+});