@ggraphic/editor 0.1.0-alpha.0 → 0.1.0-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/README.md +16 -3
  2. package/THIRD_PARTY_NOTICES +25 -1
  3. package/dist/components/CanvasContextMenu/CanvasActionSheet.js +2 -1
  4. package/dist/components/CanvasContextMenu/CanvasContextMenu.js +3 -2
  5. package/dist/components/CanvasEditor/CanvasEditorShell.js +4 -1
  6. package/dist/components/CanvasTextOverlay.js +10 -3
  7. package/dist/components/GenericCanvas.js +12 -3
  8. package/dist/components/RichTextField.js +1 -0
  9. package/dist/components/SelectionPill.js +2 -1
  10. package/dist/components/TextFormatButtons.js +7 -2
  11. package/dist/i18n/de.d.ts +12 -0
  12. package/dist/i18n/de.js +12 -0
  13. package/dist/i18n/en.js +11 -0
  14. package/dist/page/actions.d.ts +66 -0
  15. package/dist/page/actions.js +353 -0
  16. package/dist/page/config.d.ts +15 -0
  17. package/dist/page/config.js +91 -0
  18. package/dist/page/fitting.d.ts +6 -0
  19. package/dist/page/fitting.js +26 -0
  20. package/dist/page/hug.d.ts +10 -0
  21. package/dist/page/hug.js +18 -0
  22. package/dist/page/instantiate.d.ts +8 -0
  23. package/dist/page/instantiate.js +30 -0
  24. package/dist/page/logoSize.d.ts +8 -0
  25. package/dist/page/logoSize.js +29 -0
  26. package/dist/page/pageState.d.ts +41 -0
  27. package/dist/page/pageState.js +59 -0
  28. package/dist/page/seeds.d.ts +14 -0
  29. package/dist/page/seeds.js +40 -0
  30. package/dist/page/slotBudgets.d.ts +22 -0
  31. package/dist/page/slotBudgets.js +18 -0
  32. package/dist/page/templatePack.d.ts +31 -0
  33. package/dist/page/templatePack.js +55 -0
  34. package/dist/page/typography.d.ts +11 -0
  35. package/dist/page/typography.js +13 -0
  36. package/dist/sidebar/sections/CombinedTextSection.js +1 -1
  37. package/dist/sidebar/sections/GenericShareSection.js +3 -2
  38. package/dist/styles/compiled.css +2 -0
  39. package/dist/ui/alert-dialog.js +3 -2
  40. package/dist/ui/dialog.js +3 -2
  41. package/dist/ui/editorScope.d.ts +10 -0
  42. package/dist/ui/editorScope.js +9 -0
  43. package/dist/ui/popover.js +2 -1
  44. package/dist/ui/select.js +2 -1
  45. package/dist/utils/canvasLayerManager.d.ts +14 -0
  46. package/dist/utils/canvasLayerManager.js +24 -0
  47. package/dist/utils/fontMarkSupport.d.ts +10 -0
  48. package/dist/utils/fontMarkSupport.js +22 -6
  49. package/dist/utils/layerLabels.js +3 -6
  50. package/dist/utils/textUtils.js +2 -14
  51. package/package.json +13 -6
  52. package/skills/ggraphic-embed/SKILL.md +145 -0
@@ -13,11 +13,26 @@ import { aliasFontFamily } from './fontAliases.js';
13
13
  * Ersetzte Familien laufen vorher durch `aliasFontFamily`.
14
14
  */
15
15
  const FACES = {
16
- 'Instrument Sans': { bold: true, italic: true },
17
- Fraunces: { bold: true, italic: true },
18
- 'Bricolage Grotesque': { bold: true, italic: false },
16
+ 'Instrument Sans': { bold: true, italic: true, boldItalic: false },
17
+ Fraunces: { bold: true, italic: true, boldItalic: true },
18
+ 'Bricolage Grotesque': { bold: true, italic: false, boldItalic: false },
19
19
  };
20
- const NONE = { bold: false, italic: false };
20
+ const NONE = { bold: false, italic: false, boldItalic: false };
21
+ /**
22
+ * Familien, deren `bold italic` in `typography.css` ein echter Schnitt ist:
23
+ * Fraunces trägt dort Bold Italic als `italic` und Black Italic als
24
+ * `bold italic`. Nur hier gilt „kursiv schlägt fett" nicht — der Browser
25
+ * fettet nichts synthetisch, er lädt den Black-Schnitt. Den braucht die
26
+ * Betonung einiger Markenpakete.
27
+ */
28
+ const REAL_BOLD_ITALIC = new Set(['Fraunces']);
29
+ /**
30
+ * Built in, or declared by a registered brand (`BrandFonts.cuts`). Takes an
31
+ * already aliased family; the one answer `runFont` and the toolbar share.
32
+ */
33
+ export function hasRealBoldItalic(family) {
34
+ return REAL_BOLD_ITALIC.has(family) || brandCuts(family)?.boldItalic === true;
35
+ }
21
36
  /** Erste Familie aus einem CSS-Stapel, ohne Anführungszeichen. */
22
37
  export function primaryFontFamily(fontFamily) {
23
38
  return aliasFontFamily((fontFamily.split(',')[0] ?? '').trim().replace(/^['"]|['"]$/g, ''));
@@ -26,7 +41,8 @@ export function primaryFontFamily(fontFamily) {
26
41
  export function fontMarkSupport(fontFamily) {
27
42
  const family = primaryFontFamily(fontFamily);
28
43
  const cuts = brandCuts(family);
44
+ const boldItalic = hasRealBoldItalic(family);
29
45
  if (cuts)
30
- return { bold: cuts.bold === true, italic: cuts.italic === true };
31
- return FACES[family] ?? NONE;
46
+ return { bold: cuts.bold === true, italic: cuts.italic === true, boldItalic };
47
+ return { ...(FACES[family] ?? NONE), boldItalic };
32
48
  }
@@ -5,7 +5,7 @@
5
5
  * „Hintergrund“), gesperrte mit „, gesperrt“. Rein — kein React, kein Store —,
6
6
  * damit Bühnen-Beschriftung, Alt-Text und Ansagen dieselben Namen lesen.
7
7
  */
8
- import { stripMarks } from '@ggraphic/editor/composer/marks';
8
+ import { stripInlineMarks } from '@ggraphic/schema';
9
9
  import { messages } from '@ggraphic/editor/i18n/messages';
10
10
  import { getShapeDef } from '@ggraphic/editor/utils/shapes';
11
11
  import { getAssetById, isStickerLikeInstance } from './canvasAssets.js';
@@ -33,12 +33,9 @@ function templateImageName(id) {
33
33
  return undefined;
34
34
  }
35
35
  }
36
- /** Fließtext für den Namen: Inline-Marken (`**`, `==`, `++` …) und <u> weg, Leerraum zusammengezogen, gekürzt. */
36
+ /** Fließtext für den Namen: Inline-Marken (`**`, `_`, `==`, `++`, <u> …) weg, Leerraum zusammengezogen, gekürzt. */
37
37
  function shorten(text) {
38
- const flat = stripMarks(text)
39
- .replace(/<\/?u>/g, '')
40
- .replace(/\s+/g, ' ')
41
- .trim();
38
+ const flat = stripInlineMarks(text).replace(/\s+/g, ' ').trim();
42
39
  return flat.length > LAYER_TEXT_MAX ? `${flat.slice(0, LAYER_TEXT_MAX - 1).trimEnd()}…` : flat;
43
40
  }
44
41
  function named(kind, content) {
@@ -1,8 +1,8 @@
1
1
  import { layoutRichTextBlock, wrapLines } from '@ggraphic/schema';
2
- import { brandCuts, registeredBrands } from '@ggraphic/editor/brand/brandRegistry';
2
+ import { registeredBrands } from '@ggraphic/editor/brand/brandRegistry';
3
3
  import { notifyFontLoaded } from '@ggraphic/editor/hooks/useFontGeneration';
4
4
  import { aliasFontFamily, resolveFontFamily } from './fontAliases.js';
5
- import { primaryFontFamily } from './fontMarkSupport.js';
5
+ import { hasRealBoldItalic, primaryFontFamily } from './fontMarkSupport.js';
6
6
  /**
7
7
  * Simple text wrapping using character width estimation
8
8
  * @deprecated Use wrapTextAccurate() for accurate font-aware wrapping
@@ -143,18 +143,6 @@ export function effectiveAccent(text) {
143
143
  return accent ?? undefined;
144
144
  return { ...accent, fill: accentFill };
145
145
  }
146
- /**
147
- * Familien, deren `bold italic` in `typography.css` ein echter Schnitt ist:
148
- * Fraunces trägt dort Bold Italic als `italic` und Black Italic als
149
- * `bold italic`. Nur hier gilt „kursiv schlägt fett" nicht — der Browser
150
- * fettet nichts synthetisch, er lädt den Black-Schnitt. Den braucht die
151
- * Betonung einiger Markenpakete.
152
- */
153
- const REAL_BOLD_ITALIC = new Set(['Fraunces']);
154
- /** Built in, or declared by a registered brand (`BrandFonts.cuts`). */
155
- function hasRealBoldItalic(family) {
156
- return REAL_BOLD_ITALIC.has(family) || brandCuts(family)?.boldItalic === true;
157
- }
158
146
  /**
159
147
  * The family that carries the bold cut of `family`, when a registered brand
160
148
  * declares it as a family of its own (`BrandFonts.boldFamilies`):
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ggraphic/editor",
3
- "version": "0.1.0-alpha.0",
3
+ "version": "0.1.0-alpha.1",
4
4
  "license": "MPL-2.0",
5
5
  "repository": {
6
6
  "type": "git",
@@ -18,6 +18,7 @@
18
18
  "./styles/editor": "./dist/styles/editor.css",
19
19
  "./styles/tokens": "./dist/styles/tokens.css",
20
20
  "./styles/tailwind": "./dist/styles/tailwind.css",
21
+ "./styles/compiled": "./dist/styles/compiled.css",
21
22
  "./*": {
22
23
  "types": "./dist/*.d.ts",
23
24
  "import": "./dist/*.js",
@@ -25,7 +26,7 @@
25
26
  }
26
27
  },
27
28
  "dependencies": {
28
- "@ggraphic/core": "0.1.0-alpha.0",
29
+ "@ggraphic/core": "0.1.0-alpha.1",
29
30
  "@ggraphic/schema": "0.1.0-alpha.0",
30
31
  "@hocuspocus/provider": "^4.7.1",
31
32
  "@iconify-json/bi": "^1.2.7",
@@ -71,20 +72,24 @@
71
72
  "devDependencies": {
72
73
  "@napi-rs/canvas": "^1.0.13",
73
74
  "@rolldown/plugin-babel": "^0.2.4",
75
+ "@tailwindcss/node": "4.3.3",
76
+ "@tailwindcss/oxide": "4.3.3",
74
77
  "@testing-library/jest-dom": "^7.0.1",
75
78
  "@testing-library/react": "^16.3.3",
76
79
  "@testing-library/user-event": "^14.6.8",
80
+ "@types/node": "^26.3.0",
77
81
  "@types/react": "19.3.0",
78
82
  "@types/react-dom": "^19.3.0",
79
83
  "@vitejs/plugin-react": "^6.1.2",
84
+ "babel-plugin-react-compiler": "^1.0.0",
80
85
  "jsdom": "30.1.3",
81
86
  "konva": "^10.9.0",
87
+ "lightningcss": "1.33.0",
82
88
  "react-konva": "^19.3.2",
89
+ "tailwindcss": "4.3.3",
83
90
  "typescript": "^6.0.3",
84
91
  "vitest": "^5.0.5",
85
- "vitest-axe": "^0.1.0",
86
- "@types/node": "^26.3.0",
87
- "babel-plugin-react-compiler": "^1.0.0"
92
+ "vitest-axe": "^0.1.0"
88
93
  },
89
94
  "peerDependencies": {
90
95
  "konva": "^10.9.0",
@@ -97,10 +102,12 @@
97
102
  "LICENSE",
98
103
  "NOTICE",
99
104
  "README.md",
105
+ "skills",
100
106
  "THIRD_PARTY_NOTICES"
101
107
  ],
102
108
  "scripts": {
103
- "build": "tsc --project tsconfig.build.json && node -e \"require('node:fs').cpSync('src', 'dist', { recursive: true, filter: (f) => !/\\.tsx?$/.test(f) })\"",
109
+ "build": "tsc --project tsconfig.build.json && node -e \"require('node:fs').cpSync('src', 'dist', { recursive: true, filter: (f) => !/\\.tsx?$/.test(f) })\" && node scripts/build-css.mjs",
110
+ "build:css": "node scripts/build-css.mjs",
104
111
  "lint": "eslint .",
105
112
  "test": "vitest run",
106
113
  "typecheck": "tsc --noEmit"
@@ -0,0 +1,145 @@
1
+ ---
2
+ name: ggraphic-embed
3
+ description: Embed the ggraphic canvas editor (@ggraphic/editor, @ggraphic/core, @ggraphic/schema, optionally @ggraphic/collab) in a React app. Use when installing ggraphic, mounting CanvasEditorShell, registering a brand pack, templates, messages or host services, wiring styles and fonts, or when a host build or test breaks on ggraphic (ESM-only, Tailwind classes, mocks not applying, fonts falling back).
4
+ ---
5
+
6
+ # Embedding the ggraphic editor
7
+
8
+ ggraphic is alpha (`0.1.0-alpha.x`, npm dist-tag `alpha`). APIs and the document format can change between alphas, so pin exact versions.
9
+
10
+ ## What you are signing up for
11
+
12
+ ggraphic ships the editor, not a ready-made product. Before the first render a host supplies:
13
+
14
+ 1. **At least one brand pack** (`BrandPack` from `@ggraphic/core`): colours, palettes, fonts and font faces, markers, chart colours, logo. No neutral default pack is published yet (`@ggraphic/brand-default` is not started).
15
+ 2. **At least one template**: a `FullCanvasConfig` (canvas size, sidebar tabs and sections, elements, page state, actions), registered with `defineTemplate`/`registerTemplates`. No starter config is published yet.
16
+ 3. **Host services** through `CanvasEditorProvider`: uploads, media library, image URLs, file delivery and optional features (AI, background removal, icon search).
17
+ 4. **Styles and fonts** (see below).
18
+
19
+ ggraphic Studio (`apps/studio` in the ggraphic repository) is a complete working host to read. It is **AGPL-3.0**: read it to understand, but do not copy its code into a host that is not AGPL. The packages themselves are MPL-2.0 and can be embedded in any app.
20
+
21
+ ## Install
22
+
23
+ ```bash
24
+ npm install --save-exact @ggraphic/editor@0.1.0-alpha.0 @ggraphic/core@0.1.0-alpha.0 @ggraphic/schema@0.1.0-alpha.0
25
+ npm install react react-dom konva react-konva @tanstack/react-query
26
+ # real-time collaboration (Yjs + Hocuspocus) only:
27
+ npm install --save-exact @ggraphic/collab@0.1.0-alpha.0
28
+ ```
29
+
30
+ - Keep `@ggraphic/*` on the **same exact version**; editor and collab must agree on the document schema.
31
+ - The packages are **ESM-only** and need Node ≥ 22 for anything that imports them on the server.
32
+ - `konva`, `react`, `react-dom` and `react-konva` are peers. Make sure the host resolves **one** React copy (Vite: `resolve.dedupe: ['react', 'react-dom']`), or hooks fail with "Cannot read properties of null (reading 'useContext')".
33
+ - pnpm with `minimumReleaseAge`: a freshly published alpha is refused for that window. Add exact `@ggraphic/<pkg>@<version>` entries to `minimumReleaseAgeExclude` (and remove them once the version is old enough).
34
+
35
+ ## Imports
36
+
37
+ Every source file is its own entry point; there is no barrel. Import the file you mean:
38
+
39
+ ```ts
40
+ import { registerBrandPacks } from '@ggraphic/editor/brand/brandRegistry';
41
+ import { registerMessages } from '@ggraphic/editor/i18n/messages';
42
+ import { defineTemplate, registerTemplates } from '@ggraphic/editor/templates/registry';
43
+ import { makeSectionDefiner } from '@ggraphic/editor/configs/factory/defineSection';
44
+ import {
45
+ CanvasEditorProvider,
46
+ type CanvasEditorServices,
47
+ } from '@ggraphic/editor/CanvasEditorProvider';
48
+ import { CanvasEditorShell } from '@ggraphic/editor/components/CanvasEditor/CanvasEditorShell';
49
+ import { browserFileDelivery, plainImageUrls } from '@ggraphic/editor/hostServices';
50
+ import { registerAssetCatalog } from '@ggraphic/editor/utils/canvasAssets';
51
+ import { registerToast } from '@ggraphic/editor/utils/editorToast';
52
+ ```
53
+
54
+ ## Startup order
55
+
56
+ Fill the module-level registers once, before the first render (for example in `main.tsx`):
57
+
58
+ ```ts
59
+ registerBrandPacks([myBrand]); // first pack is the default brand
60
+ registerMessages('en'); // 'de' | 'en', or a full message catalogue
61
+ registerTemplates(...myTemplates); // defineTemplate({ id, load: (formatId) => Promise.resolve(config) })
62
+ registerToast(myToast); // optional; the editor's notifications
63
+ registerAssetCatalog(myAssetCatalog); // optional; illustrations, emoji, blocks
64
+ ```
65
+
66
+ Registering brand packs is not optional decoration: the packs carry the default colours, the bold families and the font cuts every render reads. A test harness or server renderer that skips it draws something no user sees (for example a synthetic bold of a regular cut).
67
+
68
+ ## Mounting
69
+
70
+ ```tsx
71
+ <QueryClientProvider client={queryClient}>
72
+ <CanvasEditorProvider services={services}>
73
+ <CanvasEditorShell
74
+ initialConfigId="my-template"
75
+ initialProps={{}}
76
+ formatId="post-portrait"
77
+ onExport={(base64) => {
78
+ /* host decides */
79
+ }}
80
+ onCancel={() => {
81
+ /* leave the editor */
82
+ }}
83
+ />
84
+ </CanvasEditorProvider>
85
+ </QueryClientProvider>
86
+ ```
87
+
88
+ - The editor uses TanStack Query internally, so a `QueryClientProvider` must wrap it.
89
+ - `formatId` is one of the editor's formats (`@ggraphic/editor/formats/index`), e.g. `post-portrait`, `post-portrait-tall`, `profile-square`, `slide-16-9`.
90
+ - Pass `initialPages` to open a stored multi-page document; `exportApiRef` for programmatic export; `readOnly` to lock it; `chromeLeft` / `chromeCenter` / `chromeRight` for your own top bar items.
91
+ - `collaborative` connects a page to a Yjs room (`@ggraphic/collab`); without it the host saves the document itself.
92
+ - Konva needs `window`: in Next.js and other SSR frameworks render the editor client-only (`'use client'` plus a dynamic import with `ssr: false`).
93
+
94
+ ## Per-document brand
95
+
96
+ A document can carry its own brand: set `brand` on the template's `FullCanvasConfig` (or resolve it per page). React code inside the editor reads it through `useDocumentBrand()`; `activeBrand()` is the app-wide default. Do not re-register packs to switch brands while editors are open: it flips every open editor.
97
+
98
+ ## Styles
99
+
100
+ The components carry Tailwind v4 utility classes. Pick one of two ways to style them:
101
+
102
+ - **Any host (no Tailwind needed):** one import, everything compiled.
103
+
104
+ ```ts
105
+ import '@ggraphic/editor/styles/compiled';
106
+ ```
107
+
108
+ - Every rule sits in `@layer ggraphic`, so any unlayered host rule wins without `!important`. If your own CSS is layered, declare `ggraphic` first (`@layer ggraphic, base, …;`) to keep the same order.
109
+ - The rules apply only inside `[data-ggraphic]`, Tailwind's reset included, so your page keeps its own reset and theme. `CanvasEditorShell` renders that root, and every dialog, menu and popover the editor portals onto `<body>` carries the attribute too. If you mount editor components outside the shell, wrap them in an element with `data-ggraphic` (`EDITOR_SCOPE` from `@ggraphic/editor/ui/editorScope`).
110
+ - Do not combine it with `styles` or `styles/tailwind`.
111
+
112
+ - **Tailwind v4 host:** in your CSS, `@import 'tailwindcss'; @import '@ggraphic/editor/styles'; @import '@ggraphic/editor/styles/tailwind';`. This scans the package and maps the theme names onto the tokens. The classes then live in your Tailwind build and follow your layers.
113
+
114
+ Either way, theme the editor through the `--editor-*` custom properties. Set them on `:root` (light), on `[data-theme='dark']`, or inside `@media (prefers-color-scheme: dark)`. The defaults have zero specificity, so your values win. Dark mode follows `data-theme="dark"` on `<html>` or the system setting unless `data-theme="light"` is set.
115
+
116
+ ## Fonts
117
+
118
+ Every family a brand pack names in `fonts` / `fontFaces` must actually load in the page (`@font-face` with the real files), including each cut you declare. Declare which cuts exist in `fonts.cuts` (`{ bold, italic, boldItalic }` per family): a missing declaration makes the editor fake a cut or hide the bold/italic buttons. Families no pack declares fall back to ggraphic's open aliases.
119
+
120
+ ## Extending
121
+
122
+ - Your own SVG sources (an illustration library the host owns): augment the interface and register the source.
123
+
124
+ ```ts
125
+ declare module '@ggraphic/core' {
126
+ interface SvgSources {
127
+ myart: true;
128
+ }
129
+ }
130
+ ```
131
+
132
+ Recolour hints go into `illustrations.recolor` of the asset catalogue you pass to `registerAssetCatalog` (`IllustrationSources` in `@ggraphic/editor/utils/canvasAssets`).
133
+
134
+ - Extra host services: augment `CanvasEditorHostServices` from `@ggraphic/editor/CanvasEditorProvider`.
135
+
136
+ ## Testing a host
137
+
138
+ - **Jest** (e.g. jest-expo): the dist is ESM-only. Extend the preset's `transformIgnorePatterns` allowlist with `@ggraphic/` instead of writing your own pattern.
139
+ - **Vitest**: add `server.deps.inline: [/@ggraphic\//]`. Without it, `vi.mock()` of a module that ggraphic imports (`yjs`, `y-indexeddb`, `@hocuspocus/provider`, ...) does not reach the package, and module-level registries keep state across test files when `isolate: false`.
140
+ - Render tests and harnesses call the same startup registration as the app.
141
+ - Tools that used to read editor source files from your repo (label extractors, tour-anchor checks) now have to read `node_modules/@ggraphic/editor/dist` or list what they need.
142
+
143
+ ## Stored documents
144
+
145
+ Documents carry a schema version (`meta.schemaVersion`). A newer editor upgrades old documents on open; an older editor opens a newer document read-only. When you upgrade ggraphic across a schema version, ship a release that can **read** the new version before the one that **writes** it, so a rollback keeps working.