Skip to content

Commit e662c28

Browse files
FelixTJDietrichFelixTJDietrich
committed
docs(library): clarify controls API guidance
1 parent 1f3034c commit e662c28

6 files changed

Lines changed: 215 additions & 107 deletions

File tree

‎.changeset/unified-controls-api.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,4 @@ Embedding apps can now compose Apollon's built-in editor controls instead of acc
66

77
Imperative hosts can configure the same controls with `paletteControl()`, `zoomControl()`, `miniMapControl()`, and `defaultControls()`. Omitting `controls` keeps the default chrome, passing `[]` renders a bare canvas, and `addControl` / `updateControl` / `removeControl` manage custom or built-in controls at runtime.
88

9-
Editor-owned labels are now localizable through `labels`, `editor.setLabels(...)`, and `useLabels()`. The shared overlay layout also measures reserving bands and corner controls so diagram content and chrome stay clear under the documented responsive sizing rules.
9+
Localize the editor’s own tooltips, aria labels, and edit/assessment popovers through `labels`, `editor.setLabels(...)`, and `useLabels()`. Built-in and custom controls now stay clear of each other and keep diagram content visible across responsive layouts.

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ A pnpm + Vite monorepo (the server compiles with `tsc`, not Vite).
4242
- The library is consumed by the standalone app, the VS Code extension, and external embedders — don't couple its APIs to standalone-only assumptions; gate behind options.
4343
- The server requires `OWNER_SECRET` ≥ 32 chars in production (`openssl rand -hex 32`); local dev accepts a placeholder.
4444
- Never commit build output (`library/dist/`, `standalone/webapp/dist/`, …).
45-
- Don't hand-edit the `.changeset/*.md` entries the changelog automation will consume — create them with `pnpm changeset`.
45+
- Create changesets with `pnpm changeset`. You may edit the generated `.changeset/*.md` body for release-note quality; don't hand-edit `CHANGELOG.md` or invent changeset frontmatter by hand.
4646
- Don't put co-authored-by / agent-attribution trailers in a changeset body — it lands in `CHANGELOG.md` verbatim.
4747
- `CLAUDE.md` is a checked-in symlink to this file (git mode `120000`); on Windows, enable symlinks (`git config --global core.symlinks true`) or it checks out as plain text.
4848

‎docs/library/api.md‎

Lines changed: 19 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -153,16 +153,16 @@ Every field is optional.
153153

154154
### View and read-only state
155155

156-
| Member | Type | Purpose |
157-
| ---------------------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
158-
| `view` (getter / setter) | `ApollonView` | Read or set the active view. |
159-
| `setReadonly(readonly)` | `(boolean) => void` | Toggle read-only at runtime. Clears selection and any open popover when locking. |
160-
| `setPreviewMode(active)` | `(boolean) => void` | Overlay a snapshot on the canvas without writing to the Yjs doc. Used for version-history previews. |
161-
| `toggleInteractiveElementsMode(forceEnabled?)` | `(boolean?) => void` | Toggle (or force) the `Highlight` view for marking interactive elements. |
162-
| `setMode(mode)` | `(ApollonMode) => void` | Switch between `Modelling`, `Assessment`, and `Exporting` at runtime. |
163-
| `setScrollLock(locked)` | `(boolean) => void` | Toggle whether the canvas captures page scroll. |
164-
| `setLabels(labels)` | `(Partial<ApollonLabels>) => void` | Replace localized editor strings by merging a partial dictionary over the English defaults. |
165-
| `fitView(options?)` | `({ padding?, duration?, respectInsets? }) => void` | Zoom/pan so the whole diagram is visible (capped at `maxZoom: 1.0`). With no reserved insets and a scalar/absent `padding`, fits with a fraction (default `0.15`). When chrome is reserved — or `padding` is a per-side object — each side is padded by `inset + (per-side px ?? 16px gutter)` (the explicit px replaces the gutter; it does not stack with it). `respectInsets` (default `true`) includes the reserved [overlay control](/library/api/overlay-controls) insets; `duration` defaults to `200` ms. Retries up to 10 rAF ticks until nodes measure. |
156+
| Member | Type | Purpose |
157+
| ---------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
158+
| `view` (getter / setter) | `ApollonView` | Read or set the active view. |
159+
| `setReadonly(readonly)` | `(boolean) => void` | Toggle read-only at runtime. Clears selection and any open popover when locking. |
160+
| `setPreviewMode(active)` | `(boolean) => void` | Overlay a snapshot on the canvas without writing to the Yjs doc. Used for version-history previews. |
161+
| `toggleInteractiveElementsMode(forceEnabled?)` | `(boolean?) => void` | Toggle (or force) the `Highlight` view for marking interactive elements. |
162+
| `setMode(mode)` | `(ApollonMode) => void` | Switch between `Modelling`, `Assessment`, and `Exporting` at runtime. |
163+
| `setScrollLock(locked)` | `(boolean) => void` | Toggle whether the canvas captures page scroll. |
164+
| `setLabels(labels)` | `(Partial<ApollonLabels>) => void` | Replace localized editor strings by merging a partial dictionary over the English defaults. |
165+
| `fitView(options?)` | `({ padding?, duration?, respectInsets? }) => void` | Fit the diagram in view, capped at `maxZoom: 1.0`. Respects reserved [overlay control](/library/api/overlay-controls) insets by default; pass `respectInsets: false` to ignore them. `duration` defaults to `200` ms. |
166166

167167
### Canvas geometry
168168

@@ -181,15 +181,15 @@ Inject floating chrome (toolbars, banners, rails) into the editor's measured,
181181
inset-aware layout. See [Overlay controls](/library/api/overlay-controls) for
182182
regions, the `<ApollonControl>` React component, and the "make room" model.
183183

184-
| Member | Type | Purpose |
185-
| ------------------------------ | ------------------------------------------------- | ----------------------------------------------------------------------------------- |
186-
| `addControl(control)` | `(OverlayControlInput) => () => void` | Register a floating control; returns a disposer. Throws on a bad region / empty id. |
187-
| `updateControl(id, patch)` | `(string, Partial<OverlayControlInput>) => void` | Patch a control's options/renderer (no-op if absent; `id` is immutable). |
188-
| `removeControl(id)` | `(string) => void` | Unregister a control by id (no-op if absent); the imperative hide for a built-in. |
189-
| `hasControl(id)` | `(string) => boolean` | Whether a control with this id is registered. |
190-
| `getControl(id)` | `(string) => OverlayControlSnapshot \| undefined` | Read a registered control's current options (undefined if absent). |
191-
| `getRegionElement(region)` | `(OverlayRegion) => HTMLElement` | Stable node to `createPortal` host chrome into (keeps host React context). |
192-
| `releaseRegionElement(region)` | `(OverlayRegion) => void` | Release a region acquired via `getRegionElement`. |
184+
| Member | Type | Purpose |
185+
| ------------------------------ | ------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
186+
| `addControl(control)` | `(OverlayControlInput) => () => void` | Register a floating control; returns a disposer. Throws on a bad region / empty id. |
187+
| `updateControl(id, patch)` | `(string, Partial<OverlayControlInput>) => void` | Patch a control's options/renderer (no-op if absent; `id` is immutable). |
188+
| `removeControl(id)` | `(string) => void` | Unregister a control by id (no-op if absent); the imperative hide for a built-in. |
189+
| `hasControl(id)` | `(string) => boolean` | Whether a control with this id is registered. |
190+
| `getControl(id)` | `(string) => OverlayControlSnapshot \| undefined` | Read a registered control's current options (undefined if absent). |
191+
| `getRegionElement(region)` | `(OverlayRegion) => HTMLElement` | Stable pointer-transparent node to `createPortal` host chrome into (keeps host React context). |
192+
| `releaseRegionElement(region)` | `(OverlayRegion) => void` | Release a region acquired via `getRegionElement`. |
193193

194194
### Assessment
195195

0 commit comments

Comments
 (0)