@buoy-gg/floating-tools-core 7.0.4 → 7.0.6

package/lib/module/icons/ICONS.md

@@ -2,6 +2,19 @@
 
 A declarative, data-driven icon system for creating scalable vector-like icons using pure React components. Works on both **web** and **React Native** without SVG dependencies.
 
+> **Source of truth moved.** Icons are now authored as framework-neutral JSON in
+> `shared/icons/*.json` (the Buoy Icon Format) and **generated** into every framework —
+> React Native, web/desktop, and Flutter. The old hand-written `icon-data.ts` is gone;
+> `generated/icon-data.g.ts` replaces it and must never be edited by hand.
+>
+> - **`shared/icons/SPEC.md`** — the normative cross-framework rendering contract.
+>   It wins over this document wherever the two disagree.
+> - **`shared/icons/schema.json`** — the machine-checkable shape.
+> - **`/ICON_FORMAT_PLAN.md`** — why, and what is still being ported.
+>
+> This document remains the best *authoring* reference for the element types and
+> coordinate system. Edit the JSON, then run `pnpm icons`.
+
 ## Table of Contents
 
 - [Core Philosophy](#core-philosophy)
@@ -36,28 +49,36 @@ This separation provides:
 
 ## Quick Start
 
-### 1. Define Icon Data (`icon-data.ts`)
+### 1. Define Icon Data (`shared/icons/my-icon.json`)
 
-```typescript
-import type { IconData } from './icon-renderer';
+Icon data is **no longer written in TypeScript**. It lives as framework-neutral JSON
+in `shared/icons/`, so Flutter (and any future framework) renders the same icon.
+
+```jsonc
+{
+  "$schema": "./schema.json",
+  "name": "my-icon",
+  "colorExport": "MY_ICON_COLOR",
+  "color": "#FF6B6B",
+  "bgColor": "#000",
+  "elements": [
+    { "type": "circle", "cx": 0, "cy": 0, "r": 8, "fill": "color", "opacity": 0.9 },
+    { "type": "rect", "x": -4, "y": -4, "width": 8, "height": 8, "fill": "bg", "borderRadius": 2 }
+  ]
+}
+```
 
-export const MY_ICON_COLOR = '#FF6B6B';
+Then generate the per-framework constants:
 
-export const myIconData: IconData = {
-  color: MY_ICON_COLOR,
-  bgColor: '#000',
-  elements: [
-    { type: 'circle', cx: 0, cy: 0, r: 8, fill: 'color', opacity: 0.9 },
-    { type: 'rect', x: -4, y: -4, width: 8, height: 8, fill: 'bg', borderRadius: 2 },
-  ],
-};
+```bash
+pnpm icons        # regenerates icon-data.g.ts (and the Dart equivalent)
 ```
 
 ### 2. Create Icon Component (`my-icon.tsx`)
 
 ```typescript
 import { createIcon } from './icon-renderer';
-import { myIconData, MY_ICON_COLOR } from './icon-data';
+import { myIconData, MY_ICON_COLOR } from './generated/icon-data.g';
 
 export { MY_ICON_COLOR };
 export const MyIcon = createIcon(myIconData);
@@ -382,34 +403,36 @@ createBar(0, -4, 2, 8, { opacity: 0.5 })         // Vertical bar at 50%
 - Identify layers (back to front order matters!)
 - Choose your theme color
 
-#### 2. Add to `icon-data.ts`
+#### 2. Add `shared/icons/my-icon.json`
 
-```typescript
-// Color constant
-export const MY_ICON_COLOR = '#00BFFF';
-
-// Icon data
-export const myIconData: IconData = {
-  color: MY_ICON_COLOR,
-  bgColor: '#000',
-  elements: [
+```jsonc
+{
+  "$schema": "./schema.json",
+  "name": "my-icon",
+  "colorExport": "MY_ICON_COLOR",
+  "color": "#00BFFF",
+  "bgColor": "#000",
+  "elements": [
     // Layer 1: Background glow (behind everything)
-    { type: 'circle', cx: 0, cy: 0, r: 10, fill: 'color', opacity: 0.1 },
+    { "type": "circle", "cx": 0, "cy": 0, "r": 10, "fill": "color", "opacity": 0.1 },
 
     // Layer 2: Main shape
-    { type: 'circle', cx: 0, cy: 0, r: 8, fill: 'color', opacity: 0.9 },
+    { "type": "circle", "cx": 0, "cy": 0, "r": 8, "fill": "color", "opacity": 0.9 },
 
     // Layer 3: Details (on top)
-    { type: 'circle', cx: 0, cy: 0, r: 3, fill: '#fff', opacity: 0.3 },
-  ],
-};
+    { "type": "circle", "cx": 0, "cy": 0, "r": 3, "fill": "#fff", "opacity": 0.3 }
+  ]
+}
 ```
 
+Run `pnpm icons` to regenerate. The filename must match the `name` field, and the
+generated TS symbol is `myIconData` (`<camelName>IconData`).
+
 #### 3. Create Icon Component (`my-icon.tsx`)
 
 ```typescript
 import { createIcon } from './icon-renderer';
-import { myIconData, MY_ICON_COLOR } from './icon-data';
+import { myIconData, MY_ICON_COLOR } from './generated/icon-data.g';
 
 export { MY_ICON_COLOR };
 export const MyIcon = createIcon(myIconData);
@@ -776,12 +799,18 @@ elements: [
 ## Architecture Reference
 
 ```
-icon-data.ts           → Pure data definitions (IconData objects)
-icon-renderer.tsx      → renderIconData() + createIcon() + types
-icon-factories.ts      → Helper functions (createNode, createLine, etc.)
-icon-primitives.tsx    → Web primitives (CSS/divs)
+shared/icons/*.json        → THE SOURCE OF TRUTH. Hand-edit these.
+shared/icons/SPEC.md       → Cross-framework rendering contract
+scripts/gen-icons.mjs      → Generator (pnpm icons)
+        │
+        ├─► generated/icon-data.g.ts  → GENERATED IconData objects — never edit
+        └─► (Flutter Dart constants)
+
+icon-renderer.tsx          → renderIconData() + createIcon() + types
+icon-factories.ts          → Helper functions (createNode, createLine, etc.)
+icon-primitives.tsx        → Web primitives (CSS/divs)
 icon-primitives.native.tsx → React Native primitives (Views)
-[icon-name]-icon.tsx   → Individual icon exports
+[icon-name]-icon.tsx       → Individual icon exports
 ```
 
 ### Type Reference

package/lib/module/icons/benchmark-icon.js

@@ -3,13 +3,13 @@
 /**
  * BenchmarkIcon - Data-driven icon
  *
- * The icon is defined as pure data in icon-data.ts
+ * Defined as pure data in shared/icons/benchmark.json (Buoy Icon Format).
  * The renderer transforms it to components.
  *
- * To change: edit benchmarkIconData in icon-data.ts
+ * To change: edit that JSON, then run `node scripts/gen-icons.mjs`.
  */
 
 import { createIcon } from "./icon-renderer.js";
-import { benchmarkIconData, BENCHMARK_ICON_COLOR } from "./icon-data.js";
+import { benchmarkIconData, BENCHMARK_ICON_COLOR } from "./generated/icon-data.g.js";
 export { BENCHMARK_ICON_COLOR };
 export const BenchmarkIcon = createIcon(benchmarkIconData);

package/lib/module/icons/console-icon.js

@@ -0,0 +1,17 @@
+"use strict";
+
+/**
+ * ConsoleIcon - Data-driven icon
+ *
+ * Terminal frame with a `>_` prompt.
+ *
+ * Defined as pure data in shared/icons/console.json (Buoy Icon Format), so this
+ * is the same artwork the Flutter build renders.
+ *
+ * To change: edit that JSON, then run `node scripts/gen-icons.mjs`.
+ */
+
+import { createIcon } from "./icon-renderer.js";
+import { consoleIconData, CONSOLE_ICON_COLOR } from "./generated/icon-data.g.js";
+export { CONSOLE_ICON_COLOR };
+export const ConsoleIcon = createIcon(consoleIconData);

package/lib/module/icons/env-icon.js

@@ -3,13 +3,13 @@
 /**
  * EnvIcon - Data-driven icon
  *
- * The icon is defined as pure data in icon-data.ts
+ * Defined as pure data in shared/icons/env.json (Buoy Icon Format).
  * The renderer transforms it to components.
  *
- * To change: edit envIconData in icon-data.ts
+ * To change: edit that JSON, then run `node scripts/gen-icons.mjs`.
  */
 
 import { createIcon } from "./icon-renderer.js";
-import { envIconData, ENV_ICON_COLOR } from "./icon-data.js";
+import { envIconData, ENV_ICON_COLOR } from "./generated/icon-data.g.js";
 export { ENV_ICON_COLOR };
 export const EnvIcon = createIcon(envIconData);

package/lib/module/icons/events-icon.js

@@ -3,13 +3,13 @@
 /**
  * EventsIcon - Data-driven icon
  *
- * The icon is defined as pure data in icon-data.ts
+ * Defined as pure data in shared/icons/events.json (Buoy Icon Format).
  * The renderer transforms it to components.
  *
- * To change: edit eventsIconData in icon-data.ts
+ * To change: edit that JSON, then run `node scripts/gen-icons.mjs`.
  */
 
 import { createIcon } from "./icon-renderer.js";
-import { eventsIconData, EVENTS_ICON_COLOR } from "./icon-data.js";
+import { eventsIconData, EVENTS_ICON_COLOR } from "./generated/icon-data.g.js";
 export { EVENTS_ICON_COLOR };
 export const EventsIcon = createIcon(eventsIconData);