flet-box 1.0.8 → 1.1.0

package/README.md

@@ -23,6 +23,7 @@ Real DOM · No Virtual DOM · No build config to learn.
 <br><br>
 
 <a href="https://kuko53348.github.io/flet-box-docs/">📖 Docs</a> •
+<a href="https://kuko53348.github.io/flet-box-widgets-exemples/">🧪 Widget gallery</a> •
 <a href="#quick-start">Quick start</a> •
 <a href="https://www.youtube.com/@flet-box">▶ YouTube</a> •
 <a href="#support--sponsorship">❤️ Sponsor</a>
@@ -157,6 +158,8 @@ Read the docs online: **[The FletBox Book — kuko53348.github.io/flet-box-docs]
 
 They are **one continuous book** — the cover maps every page: [The FletBox Book source](docs/README.md).
 
+Rather than read, click: **[the live widget gallery](https://kuko53348.github.io/flet-box-widgets-exemples/)** gives every widget its own page, renders each example in the browser it was written for, and prints the exact call underneath it. The theme toggle in the corner shows the same screen in light and dark, which is the honest way to judge a default color.
+
 - [Your first app](docs/guides/first-app.md) — build a working todo app in 20 minutes
 - [The widget book](docs/widget/README.md) — every widget with property tables and examples
 - [State, Router & Services](docs/guides/state.md) — shared state, routing, storage, and HTTP

package/bin/commands/checkUi.js

@@ -109,13 +109,54 @@ export const WARN_CODES = new Set([
   "UNCONSTRAINED_FORM_WIDTH",
 ]);
 
-const INFO_CODES = new Set([
+export const INFO_CODES = new Set([
   "SMALL_PRESET",
   "CROWDED_FORM",
   "LIST_WITHOUT_STATE",
   "MULTIPLE_PRIMARY_ACTIONS",
 ]);
 
+/**
+ * Which design rule each code proves, and the number the finding prints.
+ *
+ * The gate is the machine half of a contract whose human half is
+ * `skills/fletbox-design/SKILL.md`: 25 numbered rules, read by the agent that
+ * builds the screen. A finding that says `OFF_SCALE_SPACING` tells the reader the
+ * value is wrong; a finding that says `OFF_SCALE_SPACING — rule 07` tells them to
+ * open rule 07 and learn *why*, which is the only way the next screen is right
+ * without being told twice. `scripts/check-skills.mjs` fails if a code is missing
+ * here, if a number here is not a heading in the skill, or if the skill does not
+ * name that code inside the rule it is filed under — so this table and that file
+ * cannot drift apart.
+ */
+export const CODE_RULE = {
+  RAW_COLOR: "03",
+  OFF_SCALE_SPACING: "07",
+  OFF_SCALE_RADIUS: "03",
+  OFF_SCALE_TYPE: "08",
+  SMALL_TAP_TARGET: "03",
+  LOW_CONTRAST: "11",
+  UNLABELED_FIELD: "13",
+  UNLABELED_TOGGLE: "11",
+  DESTRUCTIVE_COLOR: "14",
+  UNREADABLE: "00",
+  LOW_CONTRAST_SOFT: "11",
+  LOW_CONTRAST_UI: "11",
+  LOW_CONTRAST_ON_SURFACE: "11",
+  HAND_MIXED_COLOR: "03",
+  DEAD_ELEVATION: "10",
+  IMAGE_NO_ALT: "11",
+  ICON_ONLY_CONTROL: "11",
+  CENTERED_BODY_TEXT: "08",
+  GENERIC_ACTION_LABEL: "14",
+  CONFIRM_ORDER: "14",
+  UNCONSTRAINED_FORM_WIDTH: "13",
+  SMALL_PRESET: "03",
+  CROWDED_FORM: "06",
+  LIST_WITHOUT_STATE: "12",
+  MULTIPLE_PRIMARY_ACTIONS: "04",
+};
+
 /**
  * The legal home for a hex value is the app's own token file. Anything else in
  * `src/` that types a color by hand is the drift this rule exists to catch.
@@ -1319,7 +1360,15 @@ export const checkUi = async (argv = [], io = {}) => {
 
   if (asJson) {
     print(
-      JSON.stringify({ package: api.pkg.version, scanned: files.length, findings }, null, 2),
+      JSON.stringify(
+        {
+          package: api.pkg.version,
+          scanned: files.length,
+          findings: findings.map((item) => ({ rule: CODE_RULE[item.code] || null, ...item })),
+        },
+        null,
+        2,
+      ),
     );
   } else {
     print(
@@ -1338,10 +1387,11 @@ export const checkUi = async (argv = [], io = {}) => {
       byCode.get(item.code).push(item);
     }
     for (const [code, list] of byCode) {
+      const rule = CODE_RULE[code];
       print(
         section(
           "•",
-          `${code} — ${list.length} finding(s)`,
+          `${code}${rule ? ` — rule ${rule}` : ""} — ${list.length} finding(s)`,
           ERROR_CODES.has(code) ? "#f87171" : INFO_CODES.has(code) ? "#94a3b8" : "#fbbf24",
         ),
       );

package/bin/commands/create.js

@@ -19,8 +19,16 @@ import * as templates from "../utils/templates.js";
 import { parseGithubRepo } from "../utils/bundleConfig.js";
 import { checkApi } from "../commands/checkApi.js";
 import { unpack } from "../commands/unpack.js";
+import { skillNames, readSkill } from "../utils/skills.js";
 import { c, banner, gradient } from "../utils/colors.js";
 
+/**
+ * Skills that every screen needs, whatever the task. Their Cursor twin rule loads
+ * with the file instead of waiting to be picked by description; the rest are
+ * read when their description matches what the agent is about to do.
+ */
+const ALWAYS_ON_SKILLS = new Set(["fletbox-rules", "fletbox-design"]);
+
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
@@ -216,8 +224,8 @@ export const createProject = async (projectName, rawArgs = []) => {
     ".fletbox/api",
     ".fletbox/memory/notes",
     ".claude",
-    ".claude/skills/fletbox-clean-ui",
-    ".qoder/skills/fletbox-clean-ui",
+    ".claude/skills",
+    ".qoder/skills",
     ".cursor/rules",
   ];
   const extraDirs =
@@ -437,23 +445,36 @@ export const createProject = async (projectName, rawArgs = []) => {
     templates.cursorRules(),
   );
 
-  // The clean-UI skill. Claude Code loads `.claude/skills/<name>/SKILL.md` by
-  // description, so the agent picks it up whenever it touches a screen without
-  // being told. `.qoder/skills/` holds a byte-identical copy because Qoder reads
-  // the same shape from a different root — one text, two loaders, never two edits.
-  const cleanUiSkill = templates.cleanUiSkill();
-  createFile(
-    path.join(projectPath, ".claude/skills/fletbox-clean-ui/SKILL.md"),
-    cleanUiSkill,
-  );
-  createFile(
-    path.join(projectPath, ".qoder/skills/fletbox-clean-ui/SKILL.md"),
-    cleanUiSkill,
-  );
-  createFile(
-    path.join(projectPath, ".cursor/rules/fletbox-clean-ui.mdc"),
-    templates.cleanUiCursorRule(),
-  );
+  // The agent skills: `skills/` at the package root is the only source, one
+  // kebab-case folder per subject (rules, design, motion, memory). The app gets
+  // the same text twice over: once as `skills/` at its own root — the folder any
+  // assistant or person reads first, and the one AGENTS.md §0 indexes — and once
+  // mirrored into `.claude/skills/` and `.qoder/skills/`, because Claude Code and
+  // Qoder load a skill by frontmatter description from those two roots and offer it
+  // without being told. Cursor has no skills folder, so each skill also ships as a
+  // pointer rule in `.cursor/rules/`. One text, three loaders, never three edits.
+  const skillList = skillNames();
+  if (skillList.length === 0) {
+    console.log(
+      c(
+        "yellow",
+        "⚠️  This flet-box package ships no skills/ folder — the app will have no design or motion contract.",
+      ),
+    );
+  }
+  for (const name of skillList) {
+    const text = readSkill(name);
+    createFile(path.join(projectPath, "skills", name, "SKILL.md"), text);
+    createFile(
+      path.join(projectPath, ".claude/skills", name, "SKILL.md"),
+      text,
+    );
+    createFile(path.join(projectPath, ".qoder/skills", name, "SKILL.md"), text);
+    createFile(
+      path.join(projectPath, ".cursor/rules", `${name}.mdc`),
+      templates.skillCursorRule(name, { alwaysApply: ALWAYS_ON_SKILLS.has(name) }),
+    );
+  }
   createFile(
     path.join(projectPath, "scripts/check-ui.mjs"),
     templates.checkUiScript(finalName),
@@ -467,6 +488,10 @@ export const createProject = async (projectName, rawArgs = []) => {
     path.join(projectPath, ".fletbox/memory/notes/baseline.md"),
     templates.memoryBaselineMd(finalName, template, pkgVersion),
   );
+  createFile(
+    path.join(projectPath, ".fletbox/memory/notes/current-status.md"),
+    templates.memoryStatusMd(finalName, template),
+  );
   createFile(
     path.join(projectPath, "scripts/check-app.mjs"),
     templates.checkAppScript(finalName),

package/bin/utils/skills.js

@@ -0,0 +1,59 @@
+// bin/utils/skills.js
+//
+// The `skills/` folder at the package root is the ONLY source for the agent
+// skills. Claude Code and Qoder load `.claude/skills/<name>/SKILL.md` and
+// `.qoder/skills/<name>/SKILL.md` by frontmatter description, so `flet-box create`
+// copies each file into both roots byte-for-byte. Keeping the text in a real
+// markdown file (instead of a 450-line array of strings in templates.js) means an
+// editor, a diff and `scripts/check-skills.mjs` can all read the same bytes the
+// agent will.
+//
+// Node core only: `bin/` may not import a devDependency at module scope.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+/** Absolute path of the folder that holds every shipped skill. */
+export const skillRoot = () => path.join(packageDir, "skills");
+
+/** Kebab-case folder names, sorted, skipping anything without a SKILL.md. */
+export const skillNames = () => {
+  let entries = [];
+  try {
+    entries = fs.readdirSync(skillRoot(), { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .filter((name) => fs.existsSync(path.join(skillRoot(), name, "SKILL.md")))
+    .sort();
+};
+
+/**
+ * The full skill text, frontmatter included.
+ * @throws when the skill does not exist — a missing skill is a build error, not
+ * a silent skip, or an app ships with half the contract and no one notices.
+ */
+export const readSkill = (name) =>
+  fs.readFileSync(path.join(skillRoot(), name, "SKILL.md"), "utf8");
+
+/** The `key: value` lines between the two `---` fences. */
+export const readFrontmatter = (name) => {
+  const text = readSkill(name);
+  const match = /^---\n([\s\S]*?)\n---/.exec(text);
+  if (!match) throw new Error(`skill "${name}" has no frontmatter block`);
+  const fields = {};
+  for (const line of match[1].split("\n")) {
+    const pair = /^([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/.exec(line);
+    if (pair) fields[pair[1]] = pair[2];
+  }
+  return fields;
+};
+
+/** One short sentence for a Cursor rule or an index: the description field. */
+export const skillDescription = (name) => readFrontmatter(name).description || name;