@meltemi/diagrams-project 0.0.0-stage → 1.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Architecture Studio contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,53 @@
-# Temporary Holding Version
+# @meltemi/diagrams-project
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Projects of `.meltemi` files: `project.json`, relative imports with namespaces, shared themes,
+models and stories across files, assets, plugins and limits, compiled incrementally through a
+host that can be the file system, a browser's memory or an editor's buffers.
+
+It is part of [Meltemi Diagrams](https://github.com/askenaz-dev/meltemi-diagrams#readme), diagrams as code with a canvas, motion and
+exports. Every package of the product has the same version.
+
+## Install
+
+```bash
+npm install @meltemi/diagrams-project
+```
+
+Node 22.12.0 or later. The package is an ES module with type declarations.
+
+## Use
+
+```ts
+import { Workspace, createMemoryHost } from "@meltemi/diagrams-project";
+
+const text = `language "0.2"
+
+diagram shop: flow {
+  web["Web shop"]
+  api["Orders API"]
+  db[("Orders")]
+  web -> api: "HTTPS" as call
+  api -> db: "SQL" as store
+}
+`;
+
+const host = createMemoryHost({
+  "/shop/project.json": '{ "name": "shop", "language": "0.2" }',
+  "/shop/diagrams/overview.meltemi": text,
+});
+const workspace = new Workspace(host, "/shop", { toolVersion: "1.0.0" });
+const program = workspace.compileProject();
+for (const [path, file] of program.files) {
+  console.log(path, file.compilation.diagnostics.length); // /shop/diagrams/overview.meltemi 0
+}
+```
+
+## Documentation
+
+- [Projects](https://github.com/askenaz-dev/meltemi-diagrams/blob/main/docs/language/projects.md)
+- [Plugins](https://github.com/askenaz-dev/meltemi-diagrams/blob/main/docs/plugins.md)
+- [All documentation](https://github.com/askenaz-dev/meltemi-diagrams/blob/main/docs/README.md)
+
+## Licence
+
+MIT. Third-party components and their licences are listed in [THIRD_PARTY_LICENSES.md](https://github.com/askenaz-dev/meltemi-diagrams/blob/main/THIRD_PARTY_LICENSES.md).

package/dist/assets.d.ts

@@ -0,0 +1,81 @@
+import { IconRegistry, type AssetLock, type IconPack, type IconProblem, type Library } from "@meltemi/diagrams-assets";
+import { type Diagnostic } from "@meltemi/diagrams-language";
+import type { ProjectHost } from "./host.js";
+import type { LoadedPlugin } from "./plugins.js";
+import type { ManifestResult } from "./manifest.js";
+/** Folders and files of a project's assets, relative to the root. */
+export declare const ICONS_FOLDER = "assets/icons";
+export declare const FONTS_FOLDER = "assets/fonts";
+export declare const LICENSES_FILE = "assets/licenses.json";
+/** The library file that names the icons added from the editor. */
+export declare const PROJECT_LIBRARY_FILE = "assets/libraries/project.json";
+/** The project path of an icon of an SVG folder pack: `assets/icons/<prefix>/<name>.svg`. */
+export declare function iconFilePath(prefix: string, name: string): string;
+/** What a host knows about a font file: its family and whether it may be embedded. */
+export type FontInspection = {
+    readonly ok: true;
+    readonly family: string;
+    readonly weight: number;
+    readonly style: "normal" | "italic";
+    readonly restricted: boolean;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/** Host services for assets: the built-in packs and font parsing (for example a `FontLibrary`). */
+export interface AssetServices {
+    readonly builtInPacks?: readonly IconPack[];
+    readonly inspectFont?: (data: Uint8Array, path: string) => FontInspection;
+}
+export interface LicenseEntry {
+    readonly license: string;
+    readonly title?: string;
+    readonly version?: string;
+    readonly url?: string;
+    readonly author?: string;
+    readonly redistribute?: boolean;
+    readonly opticalScale?: number;
+}
+export interface ProjectFontAsset {
+    /** Project path of the file. */
+    readonly path: string;
+    /** Path relative to the root, as written in locks and listings. */
+    readonly relative: string;
+    readonly family: string | null;
+    readonly weight: number | null;
+    readonly style: "normal" | "italic" | null;
+    readonly restricted: boolean;
+    readonly license: string | null;
+    readonly metadata: Partial<LicenseEntry>;
+    readonly integrity: string;
+}
+export interface ProjectAssets {
+    readonly registry: IconRegistry;
+    /** Project packs with the project path of their file or folder. */
+    readonly packs: readonly {
+        readonly pack: IconPack;
+        readonly path: string;
+    }[];
+    /** Libraries of `assets/libraries/` and of plugins, in that order. */
+    readonly libraries: readonly Library[];
+    readonly fonts: readonly ProjectFontAsset[];
+    /** The lock describing the assets as they are now. */
+    readonly lock: AssetLock;
+    /** The lock written in `assets.lock.json`, or null when there is none. */
+    readonly writtenLock: AssetLock | null;
+    /** Diagnostics by the project path of the file they concern. */
+    readonly diagnostics: ReadonlyMap<string, readonly Diagnostic[]>;
+    /** Every file read, so editors know when to discover again. */
+    readonly files: readonly string[];
+}
+/** The diagnostic code of an icon that cannot be used. */
+export declare function iconProblemCode(problem: IconProblem): string;
+/**
+ * Discovers and checks the assets of a project: icon packs under `assets/icons/`, fonts under
+ * `assets/fonts/`, `assets/licenses.json`, the aliases of `project.json` and the lock.
+ */
+export declare function discoverAssets(host: ProjectHost, root: string, manifest: ManifestResult, services: AssetServices, readText: (path: string) => string | undefined, listFolder: (path: string) => readonly {
+    name: string;
+    kind: "file" | "directory";
+}[], plugins?: readonly LoadedPlugin[]): ProjectAssets;
+//# sourceMappingURL=assets.d.ts.map

package/dist/assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../src/assets.ts"],"names":[],"mappings":"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"}